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Preface 


This manual describes the BASIC-PLUS programming language as imple¬ 
mented for the RSTS/E operating system. 

BASIC-PLUS is an easy language for beginning programmers to learn. It 
also provides many advanced features for experienced programmers. This 
manual is intended for all BASIC-PLUS programmers but is organized to 
help the beginner. 

Manual Structure 

This manual has four parts, each containing several chapters. The manual 
also has six appendixes. 

Part I (Chapters 1 through 6) introduces BASIC-PLUS, explains the rela¬ 
tionship between BASKD-PLUS and the RSTS/E operating system, and 
describes the commands and features used to write, run, modify, and debug 
programs. 

Part n (Chapters 7 through 9) describes elementary BASIO-PLUS fea¬ 
tures. It describes EXTEND and NOEXTEND progreun formats and 
BASKD-PLUS data types and expressions. It also introduces BASKD-PLUS 
statements such as LET, GOTO, INPUT and PRINT, and features such as 
mathematical functions and subroutines. You can solve many program¬ 
ming problems using the statements and features described in Part II. 

Part III (Chapters 10 through 13) describes the advanced features of 
BASKD-PLUS, including string functions, statement modifiers, error 
handling, and matrix manipulation statements. 

Part IV (Chapters 14 through 17) describes BASKD-PLUS data handling: 
formatted ASCII, virtual array, and block I/O files. 

The appendixes: 

• Review the BASKD-PLUS language in summary form 

• List error messages that BASKD-PLUS users can encounter 

• List hints for writing BASKD-PLUS programs that are compatible with 
BASIC-PLUS-2 

• Provide programming hints for the advanced user 

Related Documents 

The RSTS IE Primer and the Introduction to BASIC introduce the RSTS /E 
operating system and the BASKD-PLUS programming language. 

The RSTS/E System User^s Guide describes how to use RSTS/E system 
programs and how to work with files and devices. 


xiii 





The RSTS IE Programming Manual describes advanced BASIC-PLUS pro¬ 
gramming techniques, including the use of SYS system function calls and 
device-dependent features. 

See the RSTS IE Documentation Directory for more information on RSTS /E 
manuals. 


Conventions 


This manual uses the following conventions: 


Color Red print shows what you t 3 q)e in examples. 

UPPERCASE In statement descriptions, items in capital letters (LET, 
IF, and THEN, for example) must be typed exactly as 
shown. They are BASIC-PLUS keywords. 

< > Angle brackets enclose essential elements of the state¬ 
ment or command being described. For example, you 
must specify a variable and an expression in the LET 
statement: 


[LET] <variable> = <expre88ion> 

{} Braces indicate a required choice of one element among 
two or more possibilities. For example: 


IF <condition> 


THEN <8tatement> 
THEN <line nuniber> 
GOTO <line nuinber> 


[ ] Square brackets indicate an optional statement element 
or a choice of one element among two or more optional 
elements. For example: 


IF < condition > 


THEN <8tatement> 

THEN <line number> f ELSE <statenient> "I 
GOTO <line number> 1_ELSE <line number>J 


CTRL/x This symbol indicates a control key combination, such 
as CTRL/U or CTRL/O. To enter a control key combi¬ 
nation, hold the CTRL key down while you press the 
indicated key. 

The circumflex is a control character’s echo. For exam¬ 
ple, when you enter CTRL/U, the system displays "'U” 
on the terminal. The circumflex also means exponentia¬ 
tion, the mathematical operation that raises a number 
to a power. 








i This symbol represents the cursor, the blinking white 
line or rectangle that marks the current position on 
your terminal screen. 

© This symbol represents the LINE FEED key on your 
terminal. 

® This symbol represents the RETURN key on your 
terminal. 

Most examples in this manual do not show the RETURN key symbol. It 
appears in the introductory examples to help you get started but does not 
appear in the rest of the manual. If you try examples at your terminal, 
always press the RETURN key when you finish typing a command, 
immediate mode statement, or line in a program unless the example indi¬ 
cates otherwise. 

The programming examples in this manual shows programs as they appear 
when you finish entering them at the terminal, or when you display them 
on your screen with the LISTNH command. (LISTNH displays the program 
currently in memory.) In addition, most examples contain EXTEND mode 
features, such as the ampersand/RETURN key combination for line contin¬ 
uation. If you get error messages when you try the examples, your system 
probably uses NOEXTEND as the default mode. To correct the problem, 
enter the EXTEND command or enter an EXTEND statement at the begin¬ 
ning of the program. Both put BASIC-PLUS in EXTEND mode. 

This manual uses the following terms: 


BASIC-PLUS Means the BASIC-PLUS language, the BASIC-PLUS 
run-time system (the system software that accepts and 
executes BASIC-PLUS programs), or both, depending on 
the usage. 

System Means the RSTS/E operating system. 

Print and T 5 rpe BASIC)—PLUS prints on the terminal; you type at the 
keyboard. 


Statement A single BASIC-PLUS language instruction identified 

by one or more BASIC—PLUS language keywords. 


Program A series of instructions written in BASIC—PLUS or 

another programming language. 

Command An instruction that causes BASIC—PLUS or a system 

program to perform some operation immediately. 
Commands are not part of a program and are not pre¬ 
ceded by a line number. 
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PART I 
Developing 
BASIC-PLUS 
Programs 







Chapter 1 

Introduction to BASIC-PLUS 


BASIC-PLUS is a version of BASIC available on RSTS/E. (BASIC, which 
stands for Beginner’s All-purpose Symbolic Instruction Code, is a registered 
trademark of Dartmouth College.) 

BASIC—PLUS is both a programming environment and a programming 
language. The programming environment is a set of commands for working 
with programs; the programs themselves are composed of statements writ¬ 
ten in the BASIC—PLUS language. 

The BASIC—PLUS programming environment is one of several command 
environments available on RSTS/E. It is the main command environment 
on many, but not all RSTS/E systems. You can recognize BASIC-PLUS by 
its "Ready” prompt. 

The BASIC—PLUS programming language has both standard features and 
optional features. With standard features, you can solve a wide variety of 
programming problems. Optional features, on the other hand, provide more 
specialized capabilities. They let you: 

• Do more precise calculations than you can with standard features 

• Work with matrices using special statements that operate on an entire 
matrix 

• Print data in special formats 

• Take advantage of built-in mathematical functions 

This manual describes all BASIC—PLUS features and tells you which are 
optional. 
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1.1 Programming in BASIC-PLUS 

BASIC-PLUS is an interactive programming environment. After you enter 
each line in your program, BASIC—PLUS checks to make sure its format 
and syntax are correct. If they are correct, BASIC—PLUS translates the line 
into code that the system can execute. If the format and syntax are not 
correct, BASIC-PLUS prints an error message on your terminal and lets 
you reenter the line correctly. Because BASIC—PLUS translates each line 
as you enter it, you can run a program right after you finish entering it. If 
the program does not work correctly, you can easily modify and rerun 
it. The terminal session in this chapter shows interactive use of 
BASIC-PLUS. 

Immediate mode, another BASIC-PLUS feature, lets you execute state¬ 
ments without writing a complete program. When you enter statements 
into a program, you use line numbers. To enter an immediate mode state¬ 
ment, omit the line number. BASIC—PLUS executes the statement after 
you enter it instead of storing it in a program. Immediate mode operation is 
especially useful in two areas; debugging programs and performing simple 
calculations. For example, in immediate mode you can examine or 
change variables in the current program or use BASIC-PLUS as a "desktop 
calculator.” 

The following example shows how immediate mode works. To try the exam¬ 
ple, log in and then type the portions of the example in red. If you see the 
"Ready” system prompt, you are in the BASIC—PLUS environment and 
can proceed. If your system prompt is not "Ready,” you must enter the 
BASIC—PLUS environment. 

If you are on a DCL system, type the following command to enter 
BASIC-PLUS. You can recognize DCL by its "$” prompt. 

$ BASIC/BPLUS® 

If your system prompt is a different character, such as ">” or ".”, type the 
following conunand to enter BASIC-PLUS: 

>RUN *SWITCH® 

Keyboard Monitor to switch to? BASIC® 

The system displays the Ready prompt. Now type: 

PRINT 54+4B® 

BASIC-PLUS adds these two numbers and displays the result: 

100 

If you want to try the terminal session in the next section, stay in 
BASIC-PLUS. Otherwise, ts^ie RUN $SWrrCH and press the RETURN 
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key twice to return to your system’s main command environment or use the 
BYE command to log out. (BYE is described in the RSTS/E System User's 
Guide.) 

1.2 Commands and Statements 

BASIC—PLUS has both commands and statements. In general, you use 
BASIC-PLUS commands to develop programs - that is, to create, modify, 
and run them. BASIC!-PLUS statements, on the other hand, make up the 
BASIC—PLUS language. You use statements in programs to input data, do 
computations, and print results. Part I of this manual explains how to work 
with programs; Parts n, m, and IV describe the BASIC-PLUS program¬ 
ming language. 

1.2.1 BASIC-PLUS Terminal Session 

The following example introduces the BASIC-PLUS commands. It shows 
you how to create, display, save, run, retrieve, change, and replace a simple 
BASIC-PLUS program. Do not be concerned about what the statements in 
the program mean; they will be explained later. Just follow the steps below. 
Tjrpe the portions of the example shown in red. 

The sample program computes the factorial of a number. (The factorial of a 
number n is the product of all positive integers from 1 to n.) When run, the 
program asks you for a number from 1 to 15 and prints its factorial. 

This terminal session assumes that you are logged in. Although the exam¬ 
ple shows all commands and statements in uppercase, you can enter them 
in either upper- or lowercase. Once again, if you see the Ready prompt on 
your terminal, you can proceed. Otherwise, use the SWITCH program or 
the BASIC /BPLUS command to enter BASIC-PLUS. 

1.2.1.1 Creating the Program 

To create a BASIC-PLUS program, you first use the NEW command to 
name the program, and then you enter the program statements. The sam¬ 
ple program name is FACTOR. Press the RETURN key after each program 
statement. The RETURN key ends the statement and moves the cursor to a 
new line. 

NEUiS 

New file name--FACTOR® 

Ready 

10 PRINT "Enter a number between 1 and 15"® 

20 PRINT “and this proiTraM will calculate its factorial."® 

30 INPUT N® 

40 LET F=l® 

50 FOR X*1 TO N® 

80 LET F»F*X® 

70 NEXT X® 

80 PRINT "The factorial of " 5N ;" i s “ IF® 

90 END® 
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Use the DELETE key to correct tj^jing mistakes as you enter the state¬ 
ments. You can use the DELETE key only before you press the RETURN 
key; if you do not notice your mistake until after you press the RETURN 
key, retype the line number and the corrected statement. BASIC-PLUS 
replaces the incorrect line in your program with the new line. 

Suppose, for example, that you forget the first quotation mark in line 10, 
which is required for the statement to be correct. The system prints an 
epor message followed by the Ready prompt. Reenter line 10 correctly 
before t 3 q)ing other program statements. 

10 PRINT Enter a number between 1 and 15"® 

? Syntax error at line 10 

Ready 

10 PRINT "Enter a number between 1 and 15"® 

1.2.1.2 Listing the Program 

Although BASIC-PLUS checks for errors in the syntax or format of your 
BASIC-PLUS statements as you type them, it does not detect other types of 
errors. For example, BASIC—PLUS does not print an error message if you 
misspell a word inside quotation marks or if you enter a statement that is 
formatted correctly but does not produce the results you want when you run 
the program. 

Looking at yovir program is one way to check for correctness. Display the 
program on your terminal by typing: 

LIST® 

If any statements contain typing mistakes, correct them. Retype the line 
number and statement, and press the RETURN key. After making correc¬ 
tions, list the program again. 

1.2.1.3 Running the Program 

You are now ready to run the program. Type: 

RUN® 

The program prints a header line and prompts you for input with a ques¬ 
tion mark. Enter the value shown. 

FACTOR 01:50 PM 03-Feb-Bl 

Enter a number between 1 and 15 

and this program will calculate its factorials 

? 9® 

The factorial of 9 is 362880 
Ready 
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If you wish, run the program again and enter a different number. If you 
enter a number larger than 9, the result will be greater than six digits. 
BASIC-PLUS will print the result in exponential format, a mathematical 
"shorthand” used for large numbers. For example: 


RUN® 

FACTOR 01:51 PM 03-Feb-81 

Enter a number between 1 and 15 

and this proi^ram will calculate its factorial* 

? 12 ® 

The factorial of 12 is ♦479002E 9 
Ready 


1.2.1.4 Saving the Program 

The sample program is currently in memory. The program will be deleted 
from memory if you create a new program with NEW, retrieve an existing 
BASIC—PLUS program with the OLD command, run another program, or 
log out. Use the SAVE command to save the sample program in a disk file 
in your user account. The program is saved with the name FACTOR. Type: 

SAVE® 


SAVE copies the program; it does not remove the program from memory. 
Use the SAVE command to save a copy of a program after you create it. 

1.2.1.5 Retrieving and Changing the Program 

Now you are going to change the sample program. Before making any 
changes, however, use the OLD command to retrieve a "clean” copy of the 
program from disk and place it in memory. While not required, this step is 
good programming practice because it clears your memory 8a*ea. Clearing 
memory ensures that your program takes up the smallest possible amount 
of memory space. T 3 q)e: 

OLD FACTOR® 

As mentioned previously, if you use the sample program to calculate the 
factorial of a number greater than 9, it prints the result in exponential 
format. You are going to change the PRINT statement in line 80 and add a 
new line. These changes cause the program to print large numbers in a 
more readable format. Type the following lines: 

80 PRINT "The factorial of"iN5"is “5® 

85 PRINT NUM1*(F)® 
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After you type the new lines, use the LIST conunand to display the program 
on your terminal and then run the program one or more times. For 
example: 

RUN® 

FACTOR 02:03 PM 03-Feb-81 

Enter a number between 1 and 15 

and this prosram will calculate its factorial* 

? 12 ®) 

The factorial of 12 is 479002000 
Ready 


NOTE 

BASIC-PLUS has two types of math packages: single¬ 
precision and double-precision. Depending on which math 
package is installed on a system, BASIC-PLUS calculates 
numbers to six or fifteen significant digits. The two math 
packages are described later in this manual. 

This example was run on a BASIC-PLUS system with the 
single-precision math package. If your system has the 
double-precision math package, it displays the following 
value for the factorial of 12: 

479001600 

1.2.1.6 Saving the Modified Program 

The version of FACTOR that is currently in memory contains the changes 
you made, but the version of FACTOR that you saved on disk with the 
SAVE command still contains the old program. 

To replace the old version of FACTOR with the current version, type: 

REPLACE® 

Use the REPLACE command often during a BASIC—PLUS programming 
session to save changes to a program as you make them. Certain 
BASIC-PLUS commands and all system commands entered from the 
BASIC-PLUS environment delete your current program from memory. 
Thus, you can lose the latest version of your program if you do not use 
REPLACE. (Later chapters explain which commands delete your current 
program.) 

If you want to keep the old version of FACTOR, you can save the new 
version with a new name. For example: 

SAVE FACT2 

This SAVE command creates a new disk file in your account that contains 
the modified FACT2 program. From now on, always use the name FACT2 
to work with this version of the program. 
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You are finished with this terminal session. Use the BYE command to log 
out or the SWITCH program to return to your system’s main command 
environment. 

1.2.2 A Sample Program 

The terminal session introduced six BASIC-PLUS commands: NEW, LIST, 
RUN, SAVE, OLD, and REPLACE. These and other commands are 
described in detail in Chapters 4 and 5 of this manual. Now let’s look at the 
language itself, which is composed of statements. 

The program used in the terminal session illustrates the S 3 mtax of the 
BASIC—PLUS language and contains several t 3 T)es of statements. Here 
again is the sample program: 

10 PRINT "Enter a number between 1 and 15" 

20 PRINT "and this program will calculate its factorial*" 

30 INPUT N 
40 LET F=1 
50 FOR X=1 TO N 
60 LET F=F*X 
70 NEXT X 

80 PRINT "The factorial of"5N5"is "i 
85 PRINT NUM1$(F) 

90 END 

This program contains PRINT, INPUT, LET, FOR, NEXT, and END 
statements. 

You must follow certain rules when you compose BASIC-PLUS statements; 
these rules are called the syntax of the BASIC-PLUS language. Look at 
line 10 of the sample program, which contains a PRINT statement. When 
you run the program, this line causes the system to print the following text 
on your terminal: 


Enter a number between 1 and 15 

In line 10, the word PRINT, the blank space after the word PRINT, and the 
quotation marks aroimd the text are all part of the syntax of BASIC-PLUS. 
For example, one BASIC-PLUS ssmtax rule states that you must enclose 
text to be printed in quotation marks. Parts 11, III, and IV of this manual 
describe the S 3 mtax rules of the BASIC-PLUS language in detail. 

When you run the sample program, it: 

• Prints information on the terminal to indicate the input it wants 

• Accepts input 

• Performs calculations on the input 

• Prints the results, or output, on the terminal 
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of these operations corresponds to a statement or group of statements 

in the program: 

• The PRINT statements in lines 10 and 20 print information that asks for 
input. 

• The INPUT statement in line 30 accepts data. 

• Lines 40 through 70 contain statements that perform calculations on the 
data. Line 40 is a LET statement, which assigns a value to a variable; 
lines 50 through 70 are a group of statements called a FOR loop, used to 
perform an operation repetitively. 

• The PRINT statements in lines 80 and 85 print the results of these calcu¬ 
lations on the terminal. 

These and other BASIC-PLUS statements are described in detail in Parts 

n, in, and IV of this manual. 
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Chapter 2 

BASIC-PLUS and RSTS/E 


This chapter explains the relationship between the BASIC-PLUS com¬ 
mand environment and the RSTS/E operating system. It also tells you how 
to enter and leave the BASIC—PLUS environment on different types of 
RSTS/E systems. 


2.1 Terms 

To understand how you, BASIC-PLUS, and RSTS/E work together, you 
need to know these terms: 

Job 


The unit that RSTS/E uses to keep track of you (and other users) 
during a terminal session. When you log in, the system creates a job for 
you and assigns it a job number. The system uses your job number to 
keep track of everything you do from the time you log in to the time you 
log out. 

Run-Time System 

System software that manages part of the RSTS/E system. For exam¬ 
ple, the BASIC-PLUS run-time system manages the BASIO-PLUS 
programming environment. 

Keyboard Monitor 

The part of a run-time system that you communicate with. When you 
work in the BASIC—PLUS programming environment, for example, you 
type commands to the BASIC-PLUS keyboard monitor. Each RSTS/E 
keyboard monitor has an identifying "prompt” it displays when it 
expects input from you. The BASIC-PLUS keyboard monitor’s prompt 
is "Ready.” 
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Default Keyboard Monitor 

The main keyboard monitor that you work in on a RSTS/E system. You 
enter the default keyboard monitor after you log in. The system mana¬ 
ger chooses the default keyboard monitor for a particular system. 

Job Keyboard Monitor 

The keyboard monitor that manages a job. Your job keyboard monitor is 
the same as the default keyboard monitor unless you change it. Chang¬ 
ing your job keyboard monitor lets you work in a RSTS/E command 
environment that differs from the main command environment on your 
system. 

You change your job keyboard monitor by using the SWITCH program. 
After you change your job keyboard monitor, you stay in that keyboard 
monitor until you log out or use SWITCH to change keyboard monitors 
again. 

DCL (DIGITAL Command Language) 

A set of commands available on many different DIGITAL systems. DCL 
commands perform basic tasks like cop 3 ring files, printing files, and 
running programs. On RSTS/E, the DCL command environment is 
managed by the DCL run-time system. Like BASIC—PLUS, the DCL 
nm-time system has a keyboard monitor. 

CCL (Concise Command Language) 

A shorthand way to call a RSTS/E system program, a DIGITAL- 
supplied program such as EDT, or a user program and give it one line of 
input on a single command line. The system manager chooses the CCL 
commands for a particular RSTS/E system. 

2.2 The BASIC-PLUS Run-Time System 

BASIC—PLUS is one of several RSTS/E run-time systems. You communi¬ 
cate with the BASIC-PLUS run-time system through a keyboard monitor 
that vmderstands a set of commands. Many commands, such as NEW, OLD, 
COMPILE, and SAVE, act only on BASIC-PLUS programs. One command, 
RUN, can run both BASIC-PLUS programs and other types of programs: 

• RSTS/E system programs 

• DIGITAL-supplied programs such as the EDT editor 

• User programs written in languages such as BASIC-PLUS-2, COBOL, 
and MACRO 

Other keyboard monitor commands log you in and out (HELLO, BYE) and 
let you work with devices (ASSIGN, DEASSIGN). Appendix B of this 
tnannal summarizes all the BASIC—PLUS keyboard monitor commands. 

Except for the summary in Appendix B, the rest of this manual discusses 
only the BASIC-PLUS keyboard monitor commands used for program 
development. Commands such as HELLO, BYE, ASSIGN, and DEASSIGN 
are described in the RSTS/E System Usefs Guide. 
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Besides keyboard monitor commands, you can use two other kinds of com¬ 
mands in the BASIC—PLUS environment: CCL commands, which your sys¬ 
tem manager defines, and DCL commands, available if your system has the 
DCL run-time system. To enter a CCL command, tjrpe its name; to enter a 
DCL command, type the letters "DCL”, a space, and then the command 
name. Although CCL and DCL commands use other run-time systems, they 
return you to the BASIC-PLUS run-time system when they are finished. 
(Refer to the RSTS/E System User’s Guide for information on CCL com¬ 
mands and the RSTS/E DCL User's Guide for information on DCL 
commands.) 

Every run-time system has a name. The most common name for the 
BASKU—PLUS run-time system is "BASIC.” It is possible, however, for a 
system manager to give the BASIC-PLUS run-time system a different 
name. In addition, some RSTS/E systems have more than one 
BASIC—PLUS run-time system. Each may have different optional features 
and a different name. Check with your system manager for information 
about BASIC—PLUS run-time systems on your system. 

2.3 Types of RSTS/E Systems 

Some RSTS/E systems have only the BASIC-PLUS run-time system; 
others have several run-time systems installed. On systems with several 
run-time systems, one run-time system is the default keyboard monitor; 
this default is often, but not always, BASIC-PLUS. You can recognize the 
BASIC-PLUS keyboard monitor by its "Ready” prompt on yom- terminal. 
Other RSTS/E systems have run-time systems such as DCL or RSX for the 
default keyboard monitor. You can recognize DCL by its "$” prompt and 
RSX by its ">” prompt. It is important for you to know your default key¬ 
board monitor because it affects the way you work in the BASIC—PLUS 
environment. 

2.4 Using BASIC-PLUS on a BASIC-PLUS System 

If your system has only BASIC—PLUS or if BASIC—PLUS is your system’s 
default keyboard monitor, you see the Ready prompt after you log in. You 
can use BASIC!—PLUS commands such as NEW, OLD, RUN, and SAVE to 
work with BASIC-PLUS programs. You can also use CCL commands and 
run other types of programs available on your system. You stay in the 
BASIC-PLUS environment until you log out or imtil you use the SWITCH 
program to change your job keyboard monitor. 

2.5 Using BASIC-PLUS on Other RSTS/E Systems 

On RSTS/E systems that have DCL or another run-time system for the 
default keyboard monitor, you must enter the BASIC-PLUS environment 
before you can use BASIC-PLUS commands. As on BASIC-PLUS systems, 
you can use both BASIC—PLUS commands and CCL commands after you 
enter BASIC—PLUS, and you stay in BASIC—PLUS until you log out or use 
the SWITCH program. But how you enter BASIC-PLUS depends on what 
t 5 rpe of RSTS/E system you work on. 
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2.5.1 DCL Systems 

On a DCL-bfised RSTS/E system, you can enter the BASIC-PLUS envi¬ 
ronment with the BASIC/BPLUS command or the SWITCH program. 
Both methods make BASIC-PLUS your job keyboard monitor. Enter the 
BASIC/BPLUS command in response to the "$” DCL prompt: 

* BASIC/BPLUS® 

Ready 


To run the SWITCH program, enter: 

* RUN $SWITCH® 

Keyboard Monitor to switch to? BASICEIS 
Ready 

You can start using BASIC-PLUS commands when you see the Ready 
prompt. When you finish working in BASIC—PLUS, use the SWITCH pro¬ 
gram to return to the DCL environment or the BYE command to log out. 

2.5.2 Other Non-BASIC-PLUS Systems 

Some RSTS/E systems use RSX or other run-time systems for the default 
keyboard monitor. On these systems you enter BASIC—PLUS by running 
the SWITCH program. 

The following example shows how to use SWITCH to enter the 
BASIC—PLUS environment on an RSX—based RSTS/E system: 

>RUN ^SWITCH® 

Keyboard Monitor to switch to? BASICSB) 

Ready 

You can start using BASIC-PLUS commands when you see the Ready 
prompt. When you finish working in BASIC—PLUS, use the SWITCH pro¬ 
gram to return to the default keyboard monitor or use the BYE command to 
log out. 
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Chapter 3 

Overview of BASIC-PLUS Program Development 


This chapter introduces the BASIC-PLUS commands and other features 
used to develop (write, run, edit, save, and debug) programs. It also defines 
terms used often in the command descriptions in Chapters 4, 5, and 6. 

You enter BASIC)—PLUS commands at a terminal, in response to the Ready 
prompt. Because commands are not part of a program, you do not use line 
numbers. Commands cannot be abbreviated except where noted. When you 
finish typing a command, press the RETURN key. If the command is cor¬ 
rect, the system executes it and displays the Ready prompt when it is fin¬ 
ished. If the command is incorrect, the system displays an error message 
followed by the Ready prompt. 

3.1 Source and Translated Programs 

There are two types of BASIC—PLUS programs: source programs and trans¬ 
lated programs. Both source and translated programs can be stored on disk. 
A source program: 

• Is stored on disk in human-readable (ASCII) format 

• Must be translated by BASIC—PLUS before it can be executed 

• Is available to you for listing (displaying at the terminal) and for 
changing (editing and debugging) 

Source programs are stored with .BAS file tsrpes and are sometimes called 
BAS programs. Most of the commands and operations described in Part I 
work on source programs. 
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A Iranslated program: 

• Is not human-readable. Do not display it on your terminal or print it on 
the line printer. 

• Has already been translated by BASIC-PLUS and is stored in its trans¬ 
lated form, called intermediate code. 

• Is available to you for running, but not for listing or changing. 

Translated programs are stored with .BAG file types and are sometimes 
called BAG programs. 

3.2 The Current Program 

The current program is the program that you are currently working with in 
memory. You can be writing, editing, listing, running, or debugging it. This 
”ciuTent program” can be a new program that you created during the pres¬ 
ent timesharing session or an existing ("old”) program that you retrieved 
fi*om your disk storage area. It can be a source program or a translated 
program. 

When your current program is a soimce program, BASIC—PLUS always 
keeps a translated copy of it available so you can run it. But when your 
current program is a translated program, you can only run it. 
BASIC—PLUS does not keep a source copy available for listing or changing. 

Your area in memory can contain only one current program at a time. 
Creating, retrieving, or running another program (a BASIC—PLUS pro¬ 
gram or other type of program) erases your current program from memory. 

3.3 Command and Statement Summary 

Table 3—1 summarizes the BASIC-PLUS commands and shows where in 
this manual they are described. Tables 3—2 and 3-3 list BASIC—PLUS 
statements and RSTS/E features that are helpful in developing programs. 

Table 3-1: BASIC-PLUS Commands 


Command 

Purpose 

APPEND 

Merges the contents of a previously saved source program with 
the current program. See page 5-8. 

CATALOG or CAT 

Displays your file directory. See page 4-9. 

CCONT 

Continues execution of the current program after a STOP; also 
detaches your job from the terminal. CCONT is used in debugging 
and requires privilege. See page 6-9, 

COMPILE 

Saves a translated program in a disk file. See page 4-8, 

CONT 

Continues execution of the current program after a STOP. CONT 
is used in debugging. See page 6-9, 


(continued on next page) 


3-2 Overview of BASIC—PLUS Program Development 










Table 3-1; BASIC-PLUS Commands (Cont.) 


Command 

Purpose 

DELETE 

Removes one or more lines from your current program. See page 

5—2. 

EXTEND 

Puts BASIC—PLUS in EXTEND mode; allows you to run pro¬ 
grams with EXTEND mode features. See page 4—12. 

LENGTH 

Displays the amount of memory used by the current program and 
the maximum amount it can use. See page 4-10. 

LIST 

Displays the current program on your terminal. See page 4-5. 

NEW 

Clears memory and names a new program. See page 4-1. 

NOEXTEND 

Puts BASIC—PLUS in NOEXTEND mode. You can no longer run 
programs with EXTEND mode features. See page 4-12. 

OLD 

Retrieves a saved source program firom disk and places it in mem¬ 
ory. See page 4-4. 

RENAME 

Changes the name of the program currently in memory. See page 
5-3. 

REPLACE 

Copies the source program currently in memory into a disk file; 
replaces any existing file with the same name. See page 5-6. 

RUN 

Runs a program. See page 4-6. 

SAVE 

Copies the source program currently in memory into a disk file. 
SAVE does not replace an existing file with the same name. See 
page 4-7. 

SCALE 

Displays or sets the scale factor. See page 4-11. 

UNSAVE 

Deletes a file from a directory. See page 5-6. 


Table 3-2; BASIC-PLUS Statements 


Statement 

Purpose 

GOTO 

Used in immediate mode to continue program execution at a speci¬ 
fied line after a STOP. Immediate mode GOTO statements are 
useful in debugging. See page 6-9. 

KILL 

Deletes a file from a directory. See page 5-7. 

NAME-AS 

Chsmges a file name, file type, or protection code. See page 5-4. 

PRINT 

Displays values of program variables that you specify. Use 
immediate mode PRINT statements in debugging to display cur¬ 
rent variable values after a STOP. See page 6-11. 

PRINTLINE 

Displays the BASIC-PLUS variable LINE. When you halt a pro¬ 
gram with CTRL/C, LINE contains the line number where the 
halt occurred. See page 6-12. 

STOP 

Halts a program’s execution at a specified line. STOP is used 
mainly in debugging. See page 6-8. 
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Table 3-3: Control Characters and Terminal Keys 


Key 

Purpose 

CTRL/C 

Halts execution of the current program. See page &-12. 

CTRL/0 

Stops and restarts terminal output while a program is running. 
CTRL/0 can be useful in debugging. See page 6-13. 

CTRL/S 

Suspends terminal output while a program is running. CTRL/S 
can be useful in debugging. See page 6-13. 

CTRL/Q 

Resumes terminal output suspended by CTRL/S while a program 
is running. CTRL/Q can be useful in debugging. See page 6-13. 

CTRL/U 

Deletes the current terminal line. CTRL/U is useful in program 
editing. See page 5-2. 

DELETE key 

Erases the last character typed. The DELETE key is useful in 
program editing. See page 5-2. 

RUBOUT key 

Appears on some terminal keyboards instead of the DELETE key. 
Like the DELETE key, the RUBOUT key erases the last character 
typed and is useful in program editing. See page 5-2. 
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Chapter 4 

Creating and Running a BASiC-PLUS Program 


This chapter describes the BASIC—PLUS commands that create, retrieve, 
display, run, and save programs: NEW, OLD, LIST, RUN, SAVE, and 
COMPILE. In addition, it describes commands for getting information 
about programs (CATALOG, LENGTH, SCALE) and commands used to 
change modes (EXTEND, NOEXTEND). 

The commands in this chapter are grouped by fvmction; they are not neces¬ 
sarily in the order that you would vise them when developing a 
BASIC-PLUS program. If you are a new BASIC-PLUS user, review the 
sample terminal session in Chapter 1 of this manual before reading this 
chapter. The terminal session shows you the steps to follow in developing a 
simple BASIC-PLUS program. 


4.1 Creating a Program 

To create a new BASIC-PLUS program, use the NEW command and then 
enter the program statements into the system. 

4.1.1 The NEW Command 


The NEW command clears memory and names a new program. NEW 
deletes any program currently in memory. The command format is: 

NEW [filename] 
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If you do not specify a file name, NEW prompts you for one. If you press the 
RETURN key in response to the prompt, NEW names the program 
NONAME. The following examples show different ways to enter the NEW 
command: 

NEW® NEW creates a program named CASHOl. 

New File naiite--CASH01® 

NEW CASHOl® NEW creates a program named CASHOl. 

NEW® NEW creates a program named NONAME. 

New File name--® 


4.1.2 Entering the Program 

After you create a program in memory with the NEW command, you enter 
the BASIC-PLUS program statements. To enter a BASIC-PLUS state¬ 
ment, type a line number, a space or tab, and the statement. Then press the 
RETURN key. Follow these steps for each program statement. For 
example: 

10 PRINT "B"® 

20 X = 2*3® 

30 PRINT X® 

40 END® 

4.1.2.1 Correcting Typing Errors 

If you make a typing mistake, correct it with the DELETE key (RUBOUT 
on some terminals) or CTRL/U. The DELETE key erases individual char¬ 
acters. On video terminals, the deleted characters disappear; on hardcopy 
terminals, the deleted characters are printed between backslashes. Retype 
the correct characters on the same line. (Because a hardcopy terminal 
prints deleted characters between backslashes, a line with deletions can 
become difficult to read. You can reprint the line by pressing CTRL/R. 
Hold the CTRL key down and press the R key.) 

CTRL/U deletes the current line on your terminal. To enter a CTRL/U, 
hold the CTRL key down and press the U key. Unlike the DELETE key, 
CTRL/U does not erase characters from the screen. Instead, the system 
displays "*U” and moves the cursor to the next line. You can then retype 
the line. 

You can use DELETE or CTRL/U only before you press the RETURN key. 
If you notice a typing mistake after you press the RETURN key, ret 3 T)e the 
line number followed by the correct statement. 

See the following chapters or manuals for more information: 

BASIC-PLUS editing features Chapter 5 

Using a terminal RSTS/E System User’s Guide 
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4.1.2.2 Correcting Syntax Errors 


BASIC-PLUS checks each statement you enter for syntax errors after you 
press the RETURN key. If the statement is correct, the cursor waits on the 
next line for your input. If the statement has one or more syntax errors, 
BASIC-PLUS prints an error message below the incorrect statement, 
followed by the Ready prompt. To correct a syntax error, retype the line 
number followed by the corrected statement. For example: 

10 PRINT "THIS IS A TEST- 
20 PRINT THIS IB A TEST 
? Syntax error at line 20 

Ready 

20 PRINT "THIS IS A TEST" 

4.1.2.3 Program Translation 

Each time you enter a correct line of source code, BASIC-PLUS translates 
the line into code that the system can execute. BASIC—PLUS keeps this 
translated code in your current program’s memory area. 

Because BASIC-PLUS translates each line of your program as you enter it, 
you can run your program as soon as you finish entering it. See the RUN 
command for more information. 

4.1.2.4 The TEMPnn.TMP File 

When you create a program with the NEW command, the system creates 
the file TEMPnn.TMP in your account on the public structure; nn is your 
job number. TEMPnn.TMP contains the text of your source program and 
any changes you make to that text. Do not work with the TEMPnn.TMP 
file or type it on your terminal. The system uses TEMPnn.TMP as a 
"scratch file” and deletes it when you log out. It is noted here because it 
uses disk space in your area and appears in a directory listing of your files 
during a BASIC-PLUS session. 


NOTE 

Besides using NEW and entering a program in 
BASIC—PLUS, you can also create (and edit) a BASIC-PLUS 
source program with a text editor such as EDT. Assign a 
.BAS file type when you name the file. This method is not as 
interactive as using the BASIC—PLUS editing features; for 
example, you may not discover syntax errors in yom* program 
until you retrieve it with the OLD command or run it with 
the RUN command. However, you can take advantage of text 
editing features not available in BASIC—PLUS. 
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4.2 Calling an Existing Program - The OLD Command 


The OLD command retrieves a previously saved BASIC—PLUS source 
program and places it in memory. OLD deletes the program currently in 
memory. 

As OLD retrieves each line of the saved source program, it: 

• Translates the source code into executable code 

• Places the translated code in your current program’s memory area 

Besides translating the source program so you can run it (or save it on disk 
with the COMPILE command), the OLD command also makes the source 
program available to you for listing or changing. You must retrieve a saved 
source program with OLD before you can list or edit the program. 

OLD has the format: 

OLD [fllespec] 

where fllespec is a complete RSTS/E file specification of the form: 
dev:[acct]filenaine.typ /switchCes) 

Except for the file name, all parts of the file specification are optional. If 
you t 5 T)e OLD and press the RETURN key, you are prompted to enter a file 
name: 

OLD® 

OLD file name-- 

Press the RETURN key to retrieve NONAME.BAS; otherwise, enter all or 
part of a file specification. The OLD command default is a .BAS file in your 
account on the public structure. You receive an error message if the file 
does not exist or is protected against you. 

The following examples show how OLD works: 

OLD TAXES Retrieves the file TAXES.BAS from your account 

on the public structure. (You must specify the file 
type if it is not .BAS.) 

OLD TAXES.TTL Retrieves TAXES.TTL from your account on the 

public structure. When you specify a file type other 
than .BAS, be sure it is a BASIC!—PLUS source 
program. 

OLD DM 1! [200 »233] TAXES Retrieves TAXES.BAS from [200,233] on DM1:. 
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Usage Notes 

1. Make sure that any file you specify in the OLD command is a 
BASIC-PLUS source program. If you specify a different kind of file, 
BASIC—PLUS prints numerous error messages on your terminal; use 
CTRL/C to abort the OLD command. 

2. The system creates a TEMPnn.TMP file in your area when you retrieve 
a saved source program with the OLD command. The file contains the 
text of the source program you just retrieved. See the NEW command 
for information about this file. 


4.3 Displaying a Program - The LIST Command 

After you enter a new program, retrieve an existing program, or edit a 
program, display it on your terminal with the LIST command to make sure 
all statements are correct. You can display the entire program or one or 
more lines; you can display the program with or without header informa¬ 
tion. When you ask for header information, LIST displays the program 
name and the current date and time. You can use LIST to display only the 
program currently in memory. 

The LIST command has the format: 

LIST[NH] [line niunbers] 

NH means no header. The following examples show how the LIST 
command works: 

LIST 


LISTNH 
LIST 100 
LIST 100-200 
LISTNH 25»34»60-85 


Displays the entire program including header 
information. 

Displays the entire program without header information. 

Displays line 100 with header information. 

Displays lines 100 through 200 with header information. 

Displays lines 25, 34, and 60 through 85 without header 
information. 


You need not specify lines in sequential order; lines are displayed in the 
order you request. 

LIST prints a ? at the left of a program line that contains a syntax error. 
For example: 


LISTNH 
10 LET A=25 
15 LET B=38 
?20 PPRINT A+B 

Ready 
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Note that LIST sends output to yoiu* terminal only. Use the QUE program, 
the DCL PRINT command, or SAVE LP: to print a copy of your program on 
the line printer. The QUE program and the DCL PRINT command are the 
recommended methods; they place your request in the printer queue. SAVE 
LP:, on the other hand, sends output directly to the line printer if it is free. 
See the following manuals or sections in this manual for more information: 

SAVE LP: Section 4.5 

QUE program RSTS/E System User^s Guide 

DCL PRINT command RSTS/E DCL User^s Guide 

4.4 Running a Program - The RUN Command 

The RUN command runs (executes) a BASIC-PLUS source program, a 
BASIC-PLUS translated program, or any other executable program (such 
as the executable form of a BASIC—PLUS—2 or COBOL program). You can 
run the current program or a program stored on disk. 

The RUN command has the format: 

RUN(NH] [filespec] 

NH means no header. Before executing the current program, the RUN 
command prints a program header that consists of the program name and 
the current system date and time. When you run the current program, 
you can add NH to the RUN command to avoid printing this header 
information. 

The filespec is a complete RSTS/E file specification of the form: 

dev:[acct]filename.t 3 rp /switcWes) 

Use the file specification to nm a program not currently in memory. When 
you run a program not currently in memory, your current program is 
deleted from memory. 

The following examples show how RUN works: 

RUN Runs the current program. 

RUNNH Runs the current program without printing header 

information. 

RUN TAXES Runs the program TAXES in your account on the 

public structure. 

RUN DM 1:1200 >230 ] TAXES Runs the program TAXES in [200,230] on DM1:. 

When you specify the file name of a program not currently in memory: 

1. The system looks first for an executable program with the name you 
specify. An executable program is a file whose protection code includes 
the value 64. A BASIC—PLUS translated program (.BAG file) is an 
executable program. If an executable program exists, the system loads 
it and runs it. 
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2. If no executable program exists, the system looks for a BASIC-PLUS 
source program (.BAS file) with the name you specify. If the source 
program exists, the system loads it, translates it, and runs it. 

Usage Notes 

1. If you have programs with duplicate file names in your directory, 
always specify the .BAG or .BAS file type in the RUN command. If you 
do not, it is possible for the system to run an executable file that is not a 
BASIC—PLUS program. 

2. In NOEXTEND mode, you cannot run a saved program whose file name 
begins with the letters NH. BASIC—PLUS interprets these letters as 
"no header” instead of running the specified program. 

4.5 Saving a Source Program - The SAVE Command 

The SAVE command copies the source program currently in memory into a 

disk file. 

SAVE has the format: 

SAVE [filespec] 

where filespec is a complete RSTS/E file specification of the form: 

dev:[acct]filename.typ /switch(es) 

All parts of the file specification are optional. 

The following examples show how SAVE works: 


SAiJE 


Creates a file in your account on the public structure. The 
file name is your current program name; the file type is 
.BAS. 


SAUE NEWNAM Creates a file NEWNAM.BAS in your accoimt on the public 

structure. 


SAVE NEWNAM ♦ E 12 Creates a file NEWNAM.E12 in your account on the public 

structure. 

SAUE DL1:C3>222 3 Creates a file in [3,222] on DLl:. The file name is your 

current program name; the file type is .BAS. 


SAVE does not supersede existing files. If the file you specify already 
exists, you receive the message: 

?File exists-RENAME/REPLACE 

Reenter the SAVE command and specify a new file name or use the 
REPLACE command, described in Section 5.3, to replace the existing file 
with your current program. 
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Usage Notes 

1. You can use SAVE LP: to print your current program on the line 
printer. However, it is recommended that you use the QUE program or 
the DCL PRINT command instead of SAVE LP:. The QUE program and 
the DCL PRINT command place your request in the line printer queue. 
Your request is printed when the printer is available and contains 
header pages to identify it. Use SAVE LP: if your system does not have 
the QUE program or the DCL PRINT command. SAVE LP: does not 
queue your request or print identifying header pages; it simply prints 
the program on the line printer if it is free. The system displays a 
message if the line printer is busy, and your program does not get 
printed. See the RSTS/E System User's Guide for information about 
the QUE program and the RSTS IE DCL User’s Guide for information 
about the DCL PRINT command. 

2. If you use NOEXTEND mode, do not save a program with a file name 
that begins with the letters NH. When you specify the program in the 
RUN command, BASIC—PLUS interprets NH as "no header” instead of 
running the specified program. 

4.6 Saving a Translated Program - The COMPILE Command 

There are two types of BASIC—PLUS code: source code and translated code. 
When you use the RUN command to run a program, the system executes 
translated code, not source code. If only source code has been saved, 
BASIC—PLUS automatically translates the source code before it is 
executed. 

Translating a source program can take considerable system time. You can 
save this time by using the COMPILE command, which saves an image of a 
translated BASIC-PLUS program in a disk file. 

You can use the COMPILE command only on a program that is currently in 
memory. Thus, you must retrieve an existing source program with the OLD 
command before using COMPILE. (OLD translates the program as it places 
it in memory.) The COMPILE command has no effect on either the current 
program or its source file on disk. 

The COMPILE command has the format: 

COMPILE [filespec] 

where filespec is a complete RSTS/E file specification of the form: 
dev:[acct]filename.typ /switchCes) 

All parts of the file specification are optional. The default file name is your 
current program name; the default file type is .BAC. A translated program 
can be stored only on disk; therefore, the dev: portion of the file specifica¬ 
tion must be a disk pack. 
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The following examples show how the COMPILE command works: 

COMPILE Saves a translated image of your current program in a .BAC 

file in your account on the public structure. The file name is the 
current program name. 

COMPILE PROGl Saves a translated image of your current program in the file 
PROGl.BAC in your account on the public structure. 

COMPILE OL1 s Saves a translated image of your current program on disk pack 
DLl:. The file name is the current program name; the file type 
is .BAG. 

Usage Notes 

1. Translated programs are stored with a default protection code that is 
the sum of the system default (usually 60) plus 64, which indicates an 
executable file. To store the translated program with a different protec¬ 
tion code, use the /PROTECT switch. For example: 

COMPILE / PRS40 

The translated program is saved with a protection code of 104, the sum 
of 40 and 64. 

As in previous versions of RSTS/E, you can also enclose the protection 
code in angle brackets. However, it is recommended that you use the 
/PROTECT switch. See the RSTS/E System User^s Guide for more 
information about protection codes. 

2. Each translated file requires a minimum of 7 disk blocks. Thus, while 
storing translated programs saves execution time, translated programs 
can use more disk space than source programs. The translated file is 
contiguous if enough disk space is available. Otherwise, the system 
creates a noncontiguous file. 

3. If you use NOEXTEND mode, do not save a translated program with a 
file name that begins with the letters NH. When you specify the 
program in the RUN command, BASIO-PLUS interprets the letters as 
”no header” instead of running the specified program. 

4.7 Getting Information - CATALOG, LENGTH, and SCALE 

This section describes how to get a directory listing of files, display the 
length of the current program, and display the scale factor. 

4.7.1 Listing Fiies in a Directory - The CATALOG Command 

The CATALOG command displays information about all files in your direc¬ 
tory on the public structure or a private disk. For each file, CATALOG lists 
the file name and file type, file size in blocks, protection code, date of crea¬ 
tion, and date and time of last access. CATALOG has no effect on your 
current program. 
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You also Specify a directory other than your own. If you do, CATALOG 
displays information about files in the directory to which you have read 
access. (Your system manager can change the system so that CATALOG 
displays information on all files in the directory you specify, not just files to 
which you have read access.) 

The CATALOG command has the format: 

CATALOG [dev:[acct]] 

The following examples show how CATALOG works. You can abbreviate 
the command to CAT. The examples assume you have read access to the 
files. 


CATALOG 

CATALOG tl00>1023 
CATALOG 11 >21 
CATALOG DM0: 

CATALOG MMO:C200»222] 


Lists all files in your account on the public structure. 

Lists all files in [100,102] on the public structure. 

Lists all files in the system library account [1,2]. 

Lists all files in your account on disk DM0:. 

Lists all files in account [200,222] on magnetic tape 
unit MMO:. 


Here is a sample directory listing produced by the CATALOG command: 


CAT 


AVERAGE^BAS 

2 

60 

28-0ct-81 

28-0ct-81 

02:37 

PM 

PERCNT 

«BAS 

2 

BO 

28-Oct-ai 

28-0ct-81 

03:22 

PM 

TERM 

♦ DOC 

1 1 

BO 

28-0ct-81 

28-0ct-81 

04:10 

PM 

EXPENS 

♦ BAS 

29 

60 

28-0ct-81 

2B-0ct-81 

04:40 

PM 


Usage Note 

You can also use the DCL DIRECTORY command or the PIP or DIRECT 
programs to get a directory listing of your files. Unlike the CATALOG 
command, however, these methods delete your current program from 
memory. 

4.7.2 Displaying a Program’s Length in Memory - The LENGTH 
Command 

The LENGTH command displays the current program’s length in memory 
and the rwayimnm amount of memory that the program can use. The length 
of the current program is displayed in K words to the next highest IK 
increment. (K stands for 1024.) 

The LENGTH command has the format: 

LENGTH 

For example: 

LENGTH® 

5(1B)K of MeMorv used 
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In this example, the current program uses 5K words of memory; its maxi¬ 
mum allowed length is 16K words. The minimum length displayed for a 
current program is 2K words, even when you have no program in memory. 
The system reserves this memory space for its own use. 

4.7.3 Displaying the SCALE Factor - The SCALE Command 

The SCALE command controls the BASIC—PLUS scaled arithmetic feature. 
This feature, available only on systems with the double-precision math 
package, lets you avoid accumulated roundoff and truncation errors in frac¬ 
tional compututations. 

You work with scaled arithmetic by setting the scale factor. The scale 
factor determines the number of decimal places used in floating-point 
calculations during program execution. However, BASIC-PLUS estab¬ 
lishes the scale factor for a program during translation, not during 
execution. 

The SCALE command has two functions: it displays and sets the scale 
factor. This section shows how to use SCALE to display the scale factor. See 
Section 11.10 for a complete description of how to work with scaled arith¬ 
metic and how to use the SCALE command to set the scale factor. 

The scale factor has a default value of 0, which means that BASIC—PLUS 
uses no scale factor when translating a program. On systems with the 
single-precision math package, the scale factor is always 0. (On systems 
with the double-precision math package, the system manager can change 
the scale factor’s default value.) 

BASKU—PLUS keeps track of two scale factors: the current scale factor, used 
when your current program was translated, and the pending scale factor, to 
be used the next time translation occurs. One value is printed if both scale 
factors are the same. 

To display the scale factor, type: 

SCALE 

For example: 

SCALE® 

6,2 


The first number is the pending scale factor; the second is the current scale 
factor. Thus, this display tells you that your current program was trans¬ 
lated using a scale factor of 2 and that next time translation occurs the 
scale factor will be 6. 
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4.8 Changing Modes - EXTEND and NOEXTEND 

BASIC-PLUS has two modes of operation: EXTEND mode and 
NOEXTEND mode. When you work in EXTEND mode, you can use fea¬ 
tures not available in NOEXTEND mode, such as long variable names. 
However, the format requirements for your program are more stringent in 
EXTEND mode than in NOEXTEND mode. 

EXTEND is the default mode on most systems; however, the system meina- 
ger can change the default mode to NOEXTEND. It is recommended that 
you write programs in EXTEND mode for compatibility with 
BASIC-PLUS-2. NOEXTEND mode, on the other hand, is compatible with 
previous versions of BASIC-PLUS. The examples in this manual are writ¬ 
ten to execute in EXTEND mode. 

EXTEND and NOEXTEND can be used either as commands or as program 
statements. Their actions differ depending on how you use them. This sec¬ 
tion shows you how EXTEND and NOEXTEND work when used as com¬ 
mands. Section 7.5 compares the actions of EXTEND and NOEXTEND 
when used as commands and program statements and explains the differ¬ 
ence between EXTEND and NOEXTEND program formats. 

The following examples assume you are logged into a system where 
NOEXTEND is the default mode. To change to EXTEND mode, type: 

EXTEND 

You stay in EXTEND mode until you either: 

• Enter the NOEXTEND command 

• Use the NOEXTEND statement in your current program 

• Run an executable (but not a source) program 

• Enter a CCL or DCL command 

• Switch to another keyboard monitor 

• Log out 

To change back to NOEXTEND mode, type either: 

NOEXTEND 
NO EXTEND 

No change occurs'if you enter the command for the mode that the system is 
currently in. 
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Chapter 5 

Modifying BASIC~PLUS Programs 


This chapter describes commands and features for modifying existing 
BASIC—PLUS programs. Topics include: 

• Editing a program 

• Changing a program’s name or file specification 

• Replacing or deleting a program 

• Merging programs in memory 

5.1 Editing a BASIC-PLUS Program 

If you read Chapters 1 and 4 of this manual, you already know how to edit a 
BASIC—PLUS program. These chapters showed you how to correct program 
statements with the DELETE key and CTRL/U and how to replace an 
incorrect statement with a new statement. This section reviews these topics 
and introduces the DELETE command. 

The editing features of BASIC-PLUS can be used only on the program that 
is currently in memory. The program must be a source program; you cannot 
edit a translated program. Thus, before editing a BASIC-PLUS program, 
you must retrieve its source file from disk storage with the OLD command. 
Use the LIST command to display the program after you retrieve it. OLD 
and LIST are discussed in Chapter 4. 

5.1.1 Entering New Program Statements 

After retrieving a program, you add new statements or replace existing 
statements the same way you do when working with a new program. To 
add a new statement, type a new line number, a space or tab, and the 
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statement. Then press the RETURN key. BASIC-PLUS informs you of 
syntax errors after you press the RETURN key. To replace a program state¬ 
ment, simply retype the statement using the same line number. You need 
not enter line numbers in order; BASIC-PLUS orders the line numbers as 
you enter them. See Chapter 1 or 4 for examples of entering statements. 

5.1.2 Using the DELETE Key and CTRL/U 

Use the DELETE key (RUBOUT on some terminals) and CTRL/U to cor¬ 
rect typing mistakes as you enter a program statement, but before you 
press the RETURN key. The DELETE key erases the last character you 
typed; CTRL/U erases the entire line and moves the cursor to the next line. 
The following examples show the actions of the DELETE key and CTRL/U 
on a video terminal. 

Enter the following statement on your terminal but do not press the 
RETURN key: 

10 PRINT Thisi 

Note that you omitted the first quotation mark. Press the DELETE key 
four times. The DELETE key erases the characters "This” and moves the 
cursor back four spaces: 

10 PRINT X 

Now use CTRL/U to erase the rest of the line. The system displays "^U” 
and moves the cursor to the beginning of the next line on the screen: 

10 PRINT *U 
i 

You can now enter another program statement. 

Usage Notes 

1. On hardcopy terminals, the DELETE or RUBOUT key echoes the 
erased characters between backslashes. If you use this key several 
times, the line may become difficult to read. Use CTRL/R to reprint the 
line before you press the RETURN key. 

2. CTRL/U erases the current terminal line. If you continue a 
BASIC—PLUS statement on more than one line, the current terminal 
line may contain only part of the statement. CTRL/U erases only the 
portion of the statement on the current terminal line. 

5.1.3 The DELETE Command 

The DELETE com man d erases one or more lines from the current program. 
DELETE has the format: 

DELETE [line number{s)] 
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You can delete a single line by typing just the line number followed by the 
RETURN key. When you delete more than one line, you need not specify 
line numbers in sequential order. T 5 q)ing DELETE without a line number 
deletes all lines from your current program. 

The following examples show how DELETE works: 

DELETE Deletes all lines from the current program. 

DELETE 10 Deletes line 10 from the current program. 

1 0 Deletes line 10 from the current program. 

DELETE 100-200 Deletes lines 100 through 200 from the cur¬ 

rent program. 

DELETE 100-200 >20 >35 > 300-000 Deletes lines 100 through 200, line 24, line 

35, and lines 300 through 400 from the cur¬ 
rent program. 

Usage Notes 

1. Be sure to specify one or more line numbers in the DELETE command 
unless you want to delete all lines in your current program. 

2. Before deleting a program line, check your program for references to 
that line number (in GOTO statements, for example) and make the 
necessary changes to the program. 

3. The BASIC—PLUS DELETE command differs from the DCL DELETE 
command. The DCL DELETE command deletes a file from a directory. 

NOTE 

You can also use a text editor such as EDT to edit any 
BASIC—PLUS source program that you have saved in a disk 
file. While this method does not detect syntax errors, it lets 
you take advantage of text editing features not available in 
BASIC-PLUS. 

5.2 Changing a Program’s Name or File Specification 

The RENAME command and the NAME—AS statement both change the 
name of a program. However, they perform different functions. The 
RENAME command changes the name of the current program; the 
NAME-AS statement can change a program’s file name, file type, and 
protection code. 

5.2.1 The RENAME Command 

The RENAME commfind changes the name of the program currently in 
memory. The old program name is discarded. The RENAME command does 
not change the file name of a saved program on disk. The command has the 
format: 

RENAME filename 
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where filename is a RSTS/E file name. 

For example, to change the name of your current program to NEWNAM, 
type: 

RENAME NEHNAM 

If you now use SAVE to save your program, it is saved in the file 
NEWNAM.BAS by default. 

Usage Note 

The BASIC—PLUS RENAME command differs from the DCL RENAME 
command. The DCL RENAME command renames a file. 

5.2.2 The NAME-AS Statement 

Unlike the RENAME command, which changes the name of the program 
currently in memory, the NAME-AS statement can change the file name, 
file type, and protection code of a program stored on disk. 

NAME—AS can be used in a BASIC—PLUS program or as an immediate 
mode statement. When used as an immediate mode statement (without a 
line number), its acts like a command; that is, it is executed as soon as you 
press the RETURN key. This section discusses its use as an immediate 
mode statement. See Chapter 14 for information on using NAME—AS in a 
BASIC-PLUS program. 

The NAME—AS statement has the format: 

NAME <string> AS <string> 

where string is all or part of a RSTS/E file specification of the form: 
’'dev:[acct]flleiiame.typ /PR{OTECT]:n” 

Replace n with a valid RSTS/E protection code. 

As in previous versions of RSTS/E, you can also enclose the protection 
code in angle brackets. However, it is recommended that you use the 
/PROTECT switch. See the RSTS IE System User’s Guide for more infor¬ 
mation about protection codes. 

You must use single or double quotation marks around both strings. The 
file specified in the first string is renamed to the file specified in the second 
string. 

NAME-AS defaults to your account on the public structure. When you 
specify a file located in another device or account, you need only specify the 
device or accoimt in the first string. However, to retain a file type, you must 
specify it in both strings, even if you do not want to change it. If you do not, 
the renamed file has no file type. 

The following examples show how NAME—AS works: 

NAME "0LD.6AS" AS "NEM.BAS" 

Renames the file OLD.BAS to NEW.BAS. 


5-4 


Modifying BASIC-PLUS Programs 




NAME "OLD4 BAS" AS "NEW" 

Renames the file OLD.BAS to NEW. The file now has no file type. 

NAME "DMO;OLD.BAS" AS "DMO;NEW.BAS" 

Renames the file stored in your account on DM0: from OLD.BAS to 
NEW.BAS. 

NAME "DMOsOLD.BAS" AS "NEW.BAS" 

Performs the same action as the previous example. It renames the file 
stored in your account on DM0: from OLD.BAS to NEW.BAS. 

NAME "[200 fZOnOLD.BAS" AS " C200 »201 3NEW. BAS" 

Renames the file stored in [200,201] on the public structure from OLD.BAS 
to NEW.BAS. 

NAME "C200420130LD.BAS" AS "NEW.BAS" 

Performs the same action as the previous example. It renames the file 
stored in [200,201] on the public structure from OLD.BAS to NEW.BAS. 

NAME "OLD.BAS" AS "OLD.BAS/PR:40" 

Changes the protection code of OLD.BAS from its present value to 40. 

NAME "OLD.BAS" AS "NEW.BAS<40>" 

Renames the file OLD.BAS to NEW.BAS and changes its protection code 
from its present value to 40. 

Usage Notes 

1. NAME—AS cannot copy files. Thus, while NAME-AS can change the 
file name, file type, or protection code of a file located in another 
account or device, NAJVffi—AS cannot transfer a file to a different 
account or device. 

2. To use NAME-AS to change a file name or protection code, you must 
have write access to the file. 

3. When you use NAMEJ—AS to assign protection codes, the results 
depend on your privilege. 

Only privileged users can assign a protection code greater than 63 to a 
source or data file or a protection code less than 64 to an executable file. 
If a nonprivileged user specifies a protection code greater than 63 for a 
source or data file, the system subtracts 64 (the executable code) firom 
the value specified. For example: 

NAME "NEW.BAS" AS "NEW.BAS/PR:104" 

The system assigns a protection code of 40. 
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If a nonprivileged user specifies a protection code less than 64 for an 
executable file, the system adds 64 to the value specified. For example: 

NAME "NEW.BAG" AS "NEW.BAC/PR:dO" 

The system assigns a protection code of 104, the sum of 64 and 40. 

5.3 Replacing a Saved Program - The REPLACE Command 

The REPLACE command replaces a previously saved BASIC-PLUS source 
program with the program currently in memory. REPLACE performs basi¬ 
cally the same fimction as SAVE, but, unlike SAVE, it destroys any exist¬ 
ing source program on the disk with the same name. 

The REPLACE command has the format: 

REPLACE [filespec] 

where filespec is a RSTS/E file specification of the form: 

dev:[acct]filename.typ/8witch(e8) 

All parts of the file specification are optional. The following examples show 
how REPLACE works: 

REPLACE Copies the current program to a file in your 

account on the public structure. The file 
name is your current program name; the 
file type is .BAS. Replaces any file with the 
same file name and t 3 rpe. 

REPLACE NEWNAM Copies the current program to the file 

NEWNAM.BAS in yovur account on the pub¬ 
lic structure. Replaces any existing 
NEWNAM.BAS file. 

REPLACE DMO: [12.243NEWNAM.V1 Copies the current program to the 

file NEWNAM.Vl in [12,24] on DM0:. 
Replaces any existing file with the same file 
specification. 


5.4 Deleting a Saved Program 

You can delete a source or translated program from disk storage with the 
UNSAVE command or the KILL statement. 

5.4.1 The UNSAVE Command 

The UNSAVE command deletes a file from a directory. The file can be a 
BASIC-PLUS program or other t 3 ^e of file. 

The command has the format: 

UNSAVE [filespec] 
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where filespec is a RSTS/E file specification of the form: 
dev:[acct]filename.typ /switcWes) 

All parts of the file specification are optional. The default file name is your 
current program name; the default file type is .BAS. You must have write 
access to the file. The following examples show how UNSAVE works: 


UNSAi^E 


Deletes from your account on the public struc¬ 
ture a .BAS file with the same name as the cur¬ 
rent program. 

UNSAVE 

TAXES 

Deletes the file TAXES.BAS from your account 
on the public structure. 

UNSAVE 

TAXESeBAC 

Deletes the file TAXES.BAC from your account 
on the public structure. 

UNSAVE 

DLl : 

Deletes from your account on DLl: a file with 
the same name as the current program and a 
.BAS file t 3 npe. 

UNSAVE 

C200 #2013TAXES*BAC 

Deletes the file TAXES.BAC from [200,201] on 
the public structure. 


5.4.2 The KILL Statement 

Like the UNSAVE command, the KILL statement deletes a file from a 
directory. The file can be a BASIC-PLUS program or other type of file. 

The KILL statement can be used in a BASIC-PLUS program or as an 
immediate mode statement. Its use as an immediate mode statement is 
discussed here; see Chapter 14 for information on using the KILL state¬ 
ment in a program. 

The KILL statement has the format: 

KILL <string> 

where <string> is a RSTS/E file specification of the form: 
”t<iev:[acct]]filename.typ” 

You must enclose the file specification in quotation marks. The KILL state¬ 
ment defaults to a file in your account on the public structure, but, unlike 
the UNSAVE command, it has no default file name or type. You must 
specify the file name and t 3 q)e. You must also have write access to the file. 

The following examples show how the KILL statement works: 

KILL "TAXES.BAS" Deletes the file TAXES.BAS from your 

account on the public structure. 

KILL "DL1:TEST. BAC " Deletes the file TEST.BAC from your account 

on DLl:. 

KILL "DLl: C2.1243PROGl .BAS" Deletes the file PROGl.BAS from account 

[2,1241 on DLl:. 
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5.5 Merging Programs - The APPEND Command 

The APPEND command merges the contents of a previously saved 
BASIC-PLUS source program with the program currently in memoiy. The 
line munbers in the two programs determine how they are combing (see 
the Usage Notes). 

The command has the format: 

APPEND [filespec] 

where filespec is a RSTS/E file specification of the form: 

dev:[acct]filename.typ/8witch(e8) 

If you do not specify a file name, APPEND prompts you for one. The file you 
specify must be a BASIC—PLUS source program. Note that APPEND 
merges a copy of the saved program with your current program; the disk 
file is not affected. 

The following examples show how APPEND works: 

APPEND® Merges the file NONAME.BAS in your account 

Old file naitie--® on the public structure with your current 

program. 

APPEND® Merges the file PROG2.BAS in your account 

Old file name--PR0G2 on the public structure with your current 

program. 

APPEND PR0G2 Merges the file PROG2.BAS in your account on 

the public structure with your current program. 

APPEND DM0: c 1 2 * 1 2 3 PROG, V2 Merges the file PRC)G.V2 in account [12,12] on 

DM0: with your current program. 


Usage Notes 

1. APPEND works on source programs only, not translated programs. 
Both the program currently in memory and the program you specify in 
the APPEND command must be source programs. 

2. APPEND combines the two programs according to their line numbers. 
The combined program contains the lines firom both programs in 
ascending order. If both programs contain the same line number, the 
line from the appended program replaces the line in memory. 

3. To save the new program, use the SAVE or REPLACE command. 

4. APPEND lets you work with modular programs. You can write Brnnll 
programs that perform functions you need in several programs and 
store them in separate source files. You can then use APPEND to com¬ 
bine in memoiy the specific set of modules you want to run. 

5. You can include immediate mode statements (that is, statements with 
no line numbers) in a source file to be appended to your current pro¬ 
gram. (Immediate mode is described in Chapter 6.) 
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BASIC-PLUS executes immediate mode statements when it encounters 
them during an APPEND. They do not become part of your current 
program in memoiy; however, they can be used to modify variables in 
the program. 

The following example shows a possible use of immediate mode state¬ 
ments in a source file. The first statement in the file is an immediate 
mode PRINT statement, which is executed during the APPEND. (The 
rest of the statements in the file, which have line numbers, become part 
of the current program.) The PRINT statement tells you which module 
of a large program is being appended to the current program and also 
prints the time of day. 

PRINT "Appendins Payroll Calculation Routine* "iTIME*(OZ) 
20010 
20020 

« 

« 

« 

32767 END 

Note that your system manager can change BASIC-PLUS so that it 
does not execute immediate mode statements during an APPEND. 

6. The BASIC-PLUS APPEND command differs from the DCL APPEND 
command. The DCL APPEND command appends one file to the end of 
another. 

You should not use the DCL APPEND command to merge 
BASIC-PLUS source files. When you later retrieve or run the resulting 
source file, you lose program lines if the file contains more than one 
END statement. BASIC-PLUS only processes statements that appear 
before the first END statement. 

Do not merge .BAC files with the DCL APPEND command. You will 
not be able to execute the resulting file. 
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Chapter 6 

Immediate Mode and Program Debugging 


A program rarely works correctly the first time you run it. It must be tested 
and corrected. This process is called debugging. 

This chapter describes the features that BASIC-PLUS and RSTS/E pro¬ 
vide for debugging BASIC-PLUS programs. The principal BASIC-PLUS 
debugging feature is immediate mode. When used with the STOP, GOTO, 
and PRINT statements and the CONT and CCONT commands, immediate 
mode lets you debug programs without having to nm them over and over. 
Use these BASIC—PLUS debugging features to test and correct source pro¬ 
grams before you save them in translated form. 

In addition to showing how to debug a source program in immediate mode, 
this chapter shows some other uses of immediate mode, describes its limita¬ 
tions, and also describes the "Ready state.” A job is in the Ready state when 
the system is waiting for terminal input. Understanding the Ready state 
can help you debug programs. 

RSTS/E provides another tool for debugging BASIC-PLUS programs, the 
BPCREF utility program. BPCREF, the last topic presented in this chap¬ 
ter, produces a cross-reference listing of a translated BASIC-PLUS pro¬ 
gram. BPCREF is useful for debugging large and complex programs. 

Unlike the previous five chapters, which are mainly for new BASIC-PLUS 
users, this chapter is written for both new users and users who are familiar 
with the BASIC—PLUS language and have written some programs. New 
users may want to read just the section on immediate mode and the exam¬ 
ple in Section 6.3.5 to become familiar with the mechanics of debugging. 
The rest of the chapter, which describes the Ready state, the debugging 
process, and the BPCREF program, is primarily for the more experienced 
viser. 







6.1 Immediate Mode 

Immediate mode lets you execute BASIC-PLUS statements without 
writing a complete program. When you type a statement without a line 
number, BASIC-PLUS treats it like a command, translating and executing 
it immediately. On the other hand, when you tjrpe a statement with a 
line number, BASIC-PLUS translates it and stores it for later execution. 
Immediate mode is useful for two different pvirposes: debugging programs 
and performing simple calculations at your terminal. 

6.1.1 Immediate Mode Examples 

The following example shows how BASIC-PLUS treats the same statement 
typed with and without a line number. Type: 

10 PRINT 54 + 46® 

HI 


This statement produces no output on your terminal. The cursor simply 
moves to the next terminal line and waits for more input. Now t 3 T)e: 

PRINT 54 + 46® 

BASIC-PLUS prints the sum of the two numbers on your teiminal and 
then displays the Ready prompt; 

100 

Ready 


You can execute only one statement at a time in immediate mode. State¬ 
ments you type in immediate mode, however, can refer to variables defined 
in the current program or in other immediate mode statements. For 
example: 


fi = 3 

Ready 

B = ^ 

Ready 

PRINT A/B 
♦ 75 

Ready 

PRINT SOR (A"2 + B*2) 
5 

Ready 
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You can print a table of square roots with the following immediate mode 
statement: 


PRINT I»SOR(I 


) FOR I = 1 TO 10 


1 

2 

3 

a 

5 

6 

7 

8 

9 

10 


16228 


2*23607 

2*44949 

2*64575 

2*82843 

3 


1♦41421 
1*73205 
2 


6.1.2 Variable Assignments 

A value you assign to a variable with an immediate mode statement lasts 
until either: 

• You change its value with another immediate mode statement 

• A statement in your current program changes its value 

BASIC—PLUS sets all variables to 0 or the null string when you use the 
NEW, OLD, or RUN commands, enter a CCL or DCL command, switch to 
another keyboard monitor, or log out. 

6.1.3 Limitations of Immediate Mode 

Some BASIC—PLUS statements cannot be executed in immediate mode. 
These statements cannot stand alone; instead, they must interact with 
other statements in a program to produce results. These statements are: 


DEF 

DEF^ 

FNEND 

DIM 

DATA 

FOR 

WHILE 

UNTIL 

NEXT 


When you type these statements in immediate mode, BASIC-PLUS 
displays the message: 

?Illetfal in immediate mode 

Note that while FOR, WHILE, and UNTIL cannot be used as statements in 
immediate mode, they can be used as statement modifiers. The example in 
Section 6.1.1 that prints a square root table uses FOR as a statement modi¬ 
fier; see also Section 13.6. 
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In programs, you can place more than one statement on a single line by 
using the backslash (\) between statements. However, you cannot enter 
multiple statements on a single line in immediate mode. You get an error 
message and the statements are not executed. For example: 

A=l.\ PRINT A 

?Ille$al in immediate mode 
Ready 


6.2 Background for Debugging - The Ready State 

When the system is waiting for input from a job’s keyboard, the job is said 
to be in the Ready state. When you work in BASIC-PLUS, you can usually, 
but not always, recognize the Ready state by the BASIC—PLUS "Ready” 
prompt on your terminal. 

Most of the time, you only need to know that BASIC-PLUS expects input 
from you. But a more complete understanding of the Ready state can be 
helpful, especially during program debugging. Many commands and state¬ 
ments that you use during program debugging place your job in the Ready 
state. So do certain error conditions that occur during program execution. 
Thus, this section is presented as an introduction to debugging, and the 
specifics of debugging are described in the sections that follow. 

NOTE 

This description of the Ready state discusses BASIC—PLUS 
statements and concepts that are covered later in this man¬ 
ual. Cross-references to chapters and sections are provided. If 
you do not yet know the BASIC-PLUS language, you may 
want to postpone reading this section until you learn more 
about the language. 

In BASIC—PLUS, a job enters the Ready state when: 

• A program runs to completion and exits. 

• BASIC-PLUS finishes executing a command or immediate mode 
statement. 

• BASIC-PLUS finishes translating a line of code you just entered into the 
current program. (BASIC-PLUS does not display the Ready prompt after 
it translates a line of code.) 

A job also enters the Ready state when a program’s execution is halted 
before it is complete, either by the user or by the system. Halting a program 
at various points during execution to examine variables or change a pro¬ 
gram is an integral part of program debugging in BASIC-PLUS. 

The Ready state is also called the "CTRL/C state” or the "keyboard moni¬ 
tor wait state.” You may see these terms in other manuals. The SYSTAT 
and CTRL/T displays use "''C” to denote the Ready state. 
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The rest of this section describes: 


How a job executing a program enters the Ready state 


• What information about the program that was executing (called 
"program context” or "context information”) is saved 

• What to do next (for example, how to continue executing a program that 
was halted) 






6.2.1 Entering the Ready State 

A job executing a program enters the Ready state when the program runs 
to completion. In addition, certain other events cause the system to halt the 
program before execution is complete and place the job in the Ready state. 
This action occurs when the system: 

• Executes a STOP statement in the program 

• Receives a CTRL/C from the keyboard 

• Encounters an "untrapped” error, that is, one the program does not pro¬ 
cess using an ON ERROR GOTO statement 

The STOP statement and CTRL/C, which are described in Section 6.3, give 
you control over program execution. STOP, an important BASIC-PLUS 
debugging feature, lets you halt a program at specific points during execu¬ 
tion to examine or change data values or modify the program. 

Pressing CTRL/C while a program is running also halts execution. For 
example, you need to press CTRL/C to halt a program that contains a logic 
error called an infinite loop. An infinite loop is a section of code that causes 
the program to keep executing the same sequence of instructions indefi¬ 
nitely. Use CTRL/C with caution, though, because you cannot control 
where the program will halt. 

The system halts a program during execution when it encounters an error 
condition for which the program has no error-handling code. For example, 
when you run a program that tries to open a nonexistent file with an OPEN 
FOR INPUT statement, the "?Can’t find file or account” error results. If the 
program contains code to process the error, the system provides the pro¬ 
gram with information about the error and gives control to the program. 
(See Section 13.7, Error Handling, for information on how to process errors 
in a program.) If the program does not contain code to process the error, the 
system notifies you instead. It displays a message on your terminal and 
places your job in the Ready state. In this example you see: 

?Can't find file or account at line n 

Ready ^ 
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6.2.2 Program Status 

BASIC-PLUS saves information about the program that was executing and 
sometimes performs "housekeeping” actions when it places a job in the 
Beady state. The information saved and the actions performed depend on: 

• Whether or not the program is privileged 

• What caused the job to enter the Ready state 

If the program is privileged (that is, the program is stored on disk with a 
protection code that includes the value 128), BASIC—PLUS deletes the pro¬ 
gram from memory before it places the job in the Ready state. See the 
RSTS/E Programming Manual for more information about privileged pro¬ 
grams. The rest of this discussion applies to nonprivileged programs. 

BASIC—PLUS always saves the current values of program variables when 
a job nmning a nonprivileged program enters the Ready state. Program 
variables are saved when a program runs to completion; they are also saved 
after BASIC—PLUS executes an immediate mode statement. (During 
debugging, you can change the values of program variables by t 3 T)ing 
immediate mode statements.) 

Besides saving variables, BASIC—PLUS also closes all I/O (input/output) 
channels after program execution is complete. An I/O channel is a logical 
connection between your program and a file or device. Closing I/O channels 
closes files and frees devices for other use. See Chapter 14, Overview of 
Data Handling, for more information about I/O channels. 

BASIC-PLUS closes I/O chaimels when it executes either an explicit or an 
implicit END statement. An explicit END statement appears in the pro¬ 
gram. BASIC-PLUS executes an implicit END statement when the END 
statement does not appear in the program. (You can also type an END 
statement in immediate mode.) 

When a STOP statement, a CTRL/C, or an untrapped error halts a pro¬ 
gram before execution is complete, BASIC!-PLUS saves current values of 
program variables, but does not close I/O channels. In addition: 

1. When CTRL/C halts a program, the BASIC-PLUS variable LINE con¬ 
tains the line number where the halt occurred. 

2. When an untrapped error halts a program: 

• The BASIC—PLUS variable ERR contains the error number that 
halted the program. 

• The BASIC-PLUS variable ERL contains the line number where the 
error occurred. 

See Section 13.7 for more information about error handling and Appen¬ 
dix C for a list of error messages and their ERR values. 
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6.2.3 Possible Actions 


You can perform many different actions when your job is in the Ready 
state. These actions have different effects on your program context. 

If you are in the Ready state because a program ran to completion, or you 
do not want to continue executing the program that halted, you can either: 

• Enter an immediate mode statement 

• Enter a BASIC—PLUS command 

• Modify the program by changing lines or entering new lines 

• Run another program 

• Enter a system command (CCL or DCL) or run a system program 

Some BASIC-PLUS commands (such as NEW, OLD, and RUN) and all 
CCL and DCL commands delete your current program from memory, 
destroying all program context. Other BASIC-PLUS commands, such as 
LIST and SAVE, do not eiffect yoiu* cmrent program. Immediate mode 
statements do not delete your c\UTent program, but do change the values of 
any variables that you specify. 

If you are in the Ready state because of a program halt, you can continue 
executing the halted program. How to continue depends on what caused the 
progreim to halt. 

If a STOP statement or a CTRL/C halted the program, you can either: 

• Enter the CONT command or the privileged CCONT command to con¬ 
tinue executing the program at the point where it halted. (See Sections 
6.3.2 and 6.3.3.) 

• Enter an immediate mode (JOTO statement to continue execution at a 
specified line number. (See Section 6.3.4.) 

• Enter an immediate mode END statement to end the program and close 
open I/O channels. 

If an untrapped error halted the program, you can either: 

• Enter an immediate mode GOTO statement to continue execution at a 
specified line number. 

• Enter an immediate mode END statement to end the program and close 
open I/O channels. 

You cannot use CONT or CCONT to continue executing a program that 
halted because of an untrapped error. BASIC—PLUS displays the message 
”?Can’t CONTinue.” 
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6.2.4 Summary 

Table 6-1 summarizes the information presented in this section. 


Table 6-1: Program Status in the Ready State 


Cause of Halt 

Program Status 

Continuing or 
Ending Execution 

END 

Variables saved. 

I/O channels closed. 


STOP 

Variables saved. 

I/O channels open. 

CONT or CCONT 
Immediate Mode GOTO 
Immediate Mode END 

CTRL/C 

Variables saved. 

I/O channels open. 

CONT or CCONT 
Immediate Mode GOTO 


LINE contains line number where 
error occurred. 

Immediate Mode END 

Untrapped Error 

Variables saved. 

I/O channels open. 

ERR contains error number. 

ERL contains line number where 
error occurred. 

Immediate Mode GOTO 
Immediate Mode END 

Any cause; 
privileged program 

Program deleted from memory. 

I/O channels closed. 



The rest of this chapter describes in detail the BASIC-PLUS and RSTS/E 
features for debugging programs. 


6.3 Debugging in Immediate Mode 

Use of STOP statements in a program, combined with the use of CONT and 
CCONT commands and immediate mode GOTO statements, lets you; 

, • Halt a program’s execution 

• Examine variables 

• Make any necessary changes to the program 

• Continue program execution at the next line or another location 

This section describes the use of these BASIC-PLUS debugging features. 

6.3.1 The STOP Statement 

The STOP statement halts program execution and prints a message con¬ 
taining the line number where the halt occurred. For example, if you place 
a STOP statement on line 60 in a program, the following message is dis¬ 
played when the program is executed: 

Stop at line 50 

Ready 
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The program is no longer running. You can now examine data values with 
immediate mode PRINT statements or change data values with immediate 
mode LET statements. If you are working with a source program (as you 
usually are while debugging) you can also add, delete, or change lines with 
BASIC!—PLUS editing features. 

6.3.2 The CONT Command 

After you halt execution and examine or change your program, you can 
use the the CONT command to continue program execution. Enter the 
command as: 

CONT 

The program resumes execution at the line after the STOP statement. 

Usage Note 

Certain error conditions can prevent the CONT command from continuing 
program execution. If execution cannot be continued, the system displays: 

?Can't CONTinue 
Ready 

Depending on the cause of the error, run the program again, type an imme¬ 
diate mode GOTO statement to continue execution, or t 3 T)e an immediate 
mode END statement to end the program. 

6.3.3 The CCONT Command 

The CCONT command, available to privileged users only, performs the 
same action as CONT but also detaches the job from the terminal. Use it to 
resume execution of a job that needs to run for a long time without further 
terminal interaction. To enter the CCONT command, type: 

CCONT 

If you are not a privileged user, the system displays the message 
"?Ifrotection violation.” Use the CONT command to continue executing the 
program. 

6.3.4 The GOTO Statement 

Instead of continuing execution at the next line in the program after a halt, 
you can use the GOTO statement in immediate mode to resume execution 
at any line in the program. For example, enter the following statement to 
resume execution at line 100 of the program: 

% 

GOTO 100 
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Be sure to specify the correct line number. Any GOTO statement that 
causes transfer of control into or out of a FOR loop, function, or subroutine 
can cause unexpected results. 

Note that when a program halts because of an untrapped error, you can 
resume execution only with the GOTO statement, not with CONT or 
CCONT. See Section 13.7 for information on error handling. 


6.3.5 Debugging Example Using STOP and CONT 

The following example uses an octal-to-decimal conversion program that 
contains a bug. Assume that you have written the program. When you nm 
it, you find that it returns incorrect results; for example, it converts the 
octal number 23 to the decimal number 40 instead of 19. You decide to 
debug the program using STOP statements, the CONT command, and 
immediate mode. A program listing is on the next page. The step-by-step 
procedure to debug the program appears after the program listing. 

This example uses a fairly advanced BASIC-PLUS program. The program 
contains several fimctions, a FOR loop, and an error handling routine. The 
lines of text that start with an exclamation point (!) are called comments. 
Comments describe the program but do not affect its execution. Even if you 
do not fully understand how the program works, you can still step through 
the debugging procedure to become familiar with the debugging process. 


10 

20 

100 


200 


210 


300 


IThis is an octal to decimal conversion 
!It is written in extend mode* 

EXTEND 

ON ERROR GOTO 900 & 

\ PRINT 

\ PRINT "OCTAL TO DECIMAL CONOERTER" 

\ PRINT "CONVERTS NUMBERS BETWEEN 0" 

\ PRINT "AND 177777 (OCTAL) TO" & 

\ PRINT "THEIR DECIMAL EQUIVALENTS" 8c 


prod ram * 8c 


print out the 8c 
instructions 8c 

header 8c 


INPUT "OCTAL NUMBER";S$ I 

\ LX = LEN(Si) ! 

\ GOTO BOO IF LX = OX ! 

I 

IStartind with low order didit^ 8c 
•for each diditf taKe value of didit <VX) 
•multiply it by 8 to proper order (0X)> 8c 
land add result to accumulator <DX) 8c 


input char strind 8c 
det its 1 en dth 8c 
close out if &c 
1en dth is 0* 

8c 


OX = -IX 
\ DX = OX 

\ FOR ZX = LX TO IX STEP -IX 


\ OX = OX + IX 

\ VX = ASCI I(RIGHT(S$#ZX)) 

\ IF VX < 48X OR VX > 551 THEN 

PRINT "INVALID INPUT" 
\ GOTO 200 


initialize order 8: 
and accumulator 8c 
for each didit from 8c 
the low order to 8c 
the hidh order & 
inc rement order 8c 
picK UP next didit &c 
if out of rande: 8c 
print messade 8: 
asK for more input 8c 


4 


(continued on next page) 
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400 


! change ascii & 

I 10 a n ume ric & 

I and the ualue will & 

! accumulate in DX* & 

& 

f 1^0 back and do next & 
! di^it if there & 

! is one» & 

! Print the result & 

! and try another* & 


1 arse to conue rt• 
CONVERSION" & 


1. You suspect that the bug is in line 300 or 400 and therefore insert a 
STOP statement before each of these lines, at lines 250 and 350: 

250 STOP 
350 STOP 

If you now list the program, you see that it contains the STOP state¬ 
ments you inserted. 


2. Now run the program and input the octal number 23. The program 
stops at line 250: 

RUNNH 

OCTAL TO DECIMAL CONVERTER 
CONVERTS NUMBERS BETWEEN 0 
AND 177777 (OCTAL) TO 
THEIR DECIMAL EQUIVALENTS 
OCTAL NUMBER? 23 
Stop at line 250 

Ready 


3. Check the value of the variable L%, which contains the number of 
digits in the octal number you input. Issue a PRINT statement in 
immediate mode: 

PRINT LZ 
2 

Ready 


VX « VX AND 7X 

\ DX = DX + (VX # INT(8X * OX)) 

\ NEXT ZX 


500 

PRINT "DECIMAL VALUE IS ";NUM1»(DX) 

\ GOTO 200 


600 

GOTO 32767 


700 

! This error routine handles numbers 

too 

900 

IF ERL = 400 THEN & 



PRINT "NUMBER "jSSj" TOO BIG 
\ RESUME 200 

FOR 

910 

PRINT ERRtERL & 

\ RESUME 32767 


327G7 

END 
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4. The value of L% is correct; 23 has 2 digits. T 3 rpe the CONT command to 
continue program execution. The program stops at the next STOP 
statement. 

CONT 

Stop at line 350 
Ready 

5. Now check the values of the variables D%, 0%, V%, and Z%. Issue 
another PRINT statement in immediate mode: 

PRINT DZ»QZ.VZ*ZZ 

0 1 51 2 

You see that the value of 0%, printed as 1, should be 0 at this point in 
the program. (The program is using the digit in position 0 and 0% was 
initialized to -1.) You list the program and find the error in the sixth 
text line at line 300, where 0% (the letter variable that stands for 
"order”) was mist 3 T)ed as 0% (zero). 

6. If you wish, you can now ret 3 rpe line 300 or use a text editor to correct 
the typing error and then run the program again: 


initialize order & 
and accumulator & 
for each di^it from & 
the low order to & 
the hi^h order & 
inc rement order & 
picK UP next di^it & 
if out of ran^e: & 
print message 8: 
ask for more input & 

RUNNH 

OCTAL TO DECIMAL CONVERTER 
CONVERTS NUMBERS BETWEEN 0 
AND 177777 (OCTAL) TO 
THEIR DECIMAL EQUIVALENTS 
OCTAL NUMBER? 23 
DECIMAL VALUE IS 19 


300 QX = -IX 
\ DX = OX 

\ FOR ZX = LX TO IX STEP -IX 


OX = OX + IX 

VX = ASCII(RIGHT(S$»ZX)) 

IF VX < ASX OR VX > 55X THEN 
PRINT “INVALID INPUT" 
GOTO 200 


After making one or more corrections, use the REPLACE command to save 
the latest version of your program in a disk file. See Section 5.3. 


6.4 Halting and Checking Execution - CTRL/C and PRINT LINE 

Pressing CTRL/C while a program is running also halts program execu¬ 
tion. However, CTRL/C gives you less control over where the program 
halts than the STOP statement because you cannot specify where the halt 
is to occur. 
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When a program is halted by CTRL/C, the special variable LINE contains 
the line number of the statement being executed at the time of the halt. 
After using CTRL/C, you can display the contents of LINE by typing a 
PRINT LINE statement in immediate mode: 


“C 


Ready 

PRINT LINE 
300 

Ready 

Use the CONT command, the CCONT command, or an immediate mode 
GOTO statement to continue program execution. 

Notes 

1. If a multi-statement line is being executed when CTRL/C interrupts a 
program, you cannot determine where in the line the program stopped. 

2. Special programming techniques are available to prevent program 
interruption by CTRL/C. See the RSTS/E Programming Manual. 

6.5 Controlling Terminal Output 

Sometimes you may want to stop and restart output to your terminal while 
a program is running without stopping program execution. Several control 
keys allow you to do this. 

6.5.1 Stopping Output with CTRL/0 

CTRL/0 stops output to the terminal without stopping program execution. 
The program continues to produce output, but the system discards it. The 
system often, but not always, displays the Ready prompt when the program 
is finished. 

If you want to resume terminal output before the program is finished nm- 
ning, press CTRL/O again. 

A program cannot determine whether a CTRL/O has been entered at the 
terminal. However, there is a system function call that cancels the effect 
of a CTRL/O that has been entered. Refer to the RSTSIE Programming 
Manual for more information. 

6.5.2 Suspending and Resuming Output with CTRL/S 
and CTRL/Q 

If your terminal has the STALL characteristic set (most video terminals 
do), you can use CTRL/S and CTRL/Q to suspend and resume terminal 
output while a program is running. Press CTRL/S to suspend output; press 
CTRL/Q to resume it. 
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The system handles CTRL/S and CTRL/Q differently than CTRL/0. TTie 
system saves program output after you press CTRL/S instead of discarding 
it. Thus, all output is displayed after you press CTRL/Q. If the program 
finishes executing after you press CTRL/S, the system does not display the 
Ready prompt until you press CTRL/Q. 

(See the RSTS/E System Usefs Guide for information about the STALL 
characteristic.) 

6.5.3 Suspending and Resuming Output with the NO SCROLL Key 

The NO SCROLL key on the VTIOO terminal performs the same function 
as CTRL/S and CTRL/Q. The terminal STALL characteristic must be set. 
Press NO SCROLL to suspend terminal output while a program is running; 
press NO SCROLL again to resume terminal output. 

(See the RSTS/E System User^s Guide for information about the STALL 
characteristic.) 


6.6 Getting a Cross-Reference Listing - The BPCREF Program 

The BPCREF (BASIC—PLUS cross reference) program is a useful debug¬ 
ging tool for large and complex programs. BPCREF produces a cross- 
reference listing of a translated BASIC—PLUS (.BAC) program. The default 
listing includes variables, line number references, and some statistical 
data. You can ask BPCREF to include the source file in the listing, print 
local or global references, and queue the output to the line printer spooler. 

The references in the BPCREF listing can help you find errors in your 
program and assist you in modifying your code. For exeunple, local 
and global references can be useful when you segment a BASIC-PLUS 
program into chainable modules or convert a BASIC-PLUS program to 
BASia-PLUS-2. 

BPCREF works only on BASIC—PLUS translated images (that is, .BAC 
files). It does not work on BASIC-PLUS source files or BASIC-PLUS-2 
object code or task images. 

6.6.1 Running BPCREF 

Check with your system manager to find out where BPCREF is installed. If 
it is installed in the system library account, type the following command to 
nm it: 

RUN $BPCREF 

BF*CREF prints a header line and prompts you for input; 

BPCREF command? 
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You need to specify the files to be processed. Type the command in the 
format: 

output.crf=input.bac [.input.bas] [/switches] 
where: 

output.crf is the cross-reference listing file. 

input.bac is the translated file to process. 

input.bas is the source file to include in the listing. 

/ switches are one or more switches that specify the action to be taken on 

the files. 

You need not specify the entire command line as shown; there are defaults 
for both file names and types. Note that you can use the /SOURCE switch 
to include a listing of the .BAS file if it has the same file name and is 
located in the same accoimt as the .BAG file. Otherwise, you must specify 
the source file in the BPCREF command. Table 6—2 shows several ways to 
enter the BPCREF command and describes the result. 


Table 6-2: BPCREF Command Formats 


Format 

Result 


filel 

BPCREF examines filel.BAG and produces an output file with the 
same name and the file type .CRF. 

filel =file2 

BPCREF examines file2.BAC and produces an output 
filel.CRF. 

file named 

filel,file2 

BPCREF examines filel.BAC; includes the source 
file2.BAS in the output file filel.CRF. 

listing of 

filel =file2,file3 

BPCREF examines file2.BAC; includes in the output file filel.CRF 
the source listing of file2.BAC, which is in fileS.BAS. 


The BPCREF command switches, listed in Table 6-3, let you print the 
listing on the line printer and tailor its format and contents. You can 
abbreviate switches to one or more characters. Table 6-3 shows the 
required number of characters for each switch; optional characters are 
inside square brackets. If you use an undefined or incorrect switch in a 
command that does not include the /QUEUE switch, BPCREF prints a 
warning message and ignores the undefined switch. If you use an undefined 
or incorrect switch in a command that includes the /QUEUE switch, 
BPCREF passes the imdefined switch to the spooling program and notifies 
you with a message. 

When you use the /QUEUE switch, the output file is queued to the default 
line printer, LPO:. However, you can direct BPCREF output to a different 
printer by specifying it as the output file, for example, LPl: = filel/Q or 
LPl: = filel. The first command queues filel to LPl:; the second command 
sends filel directly to LPl:. 
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Table 6-3: BPCREF Command Switches 


Switch 

Format 

/HEL(P] 

Displays information about BPCREF command formats. 

/NODEELETE] 

Tells the spooling program not to delete the output files after printing. 

/NOH[EADER] 

Omits header lines in the output file. The resulting .CRF file is more 
suitable as input to the FILCOM program. 

/P[AGE]:nnn 

Specifies nnn as the number of lines per page to print in the output 
listing. Sixty lines per page is the default. 

/QEUEUE] 

Automatically queues the output file to the line printer. The output 
file is deleted a^r printing unless you use the /NODELETE switch. 

/S[OURCE] 

Includes the source file in the output file. Use this switch when the 
.BAS file is in the same account and has the same file name as the 
.BAG file. Otherwise, specify the source file in the BPCREF command. 

/W[IDTH]:nnn 

Sets the width of the cross reference listing to nnn columns per line. 
The default width is 132 columns; the minimum width is 72 columns. 

/GL[OW]:imn 

/GH[IGH]:nnn 

Used as a pair, these switches specify a global listing. BPCREF prints 
line numbers and variables referenced both inside and outside the 
program boundaries indicated by the line numbers nnn. BPCREF does 
not print line numbers or variables referenced only inside or outside 
the boundaries. The default value for /GL is 0 and the default value 
for /GH is 32767. 

/LL[OW]:nnn 

/LH[IGH]:imn 

Used as a pair, these switches specify a local listing. BPCREF prints 
the line numbers and variables referenced inside the program bounda¬ 
ries indicated by the line numbers nnn. BPCREF does not print line 
numbers or variables referenced outside the boundaries or referenced 
both inside and outside the boimdaries. The default value for /LL is 0 
and the default value for /LH is 32767. 

/NOC[REF] 

Omits the full cross reference listing. Use it when you want only a 
local or global listing. 


6.6.2 Output Listing Contents 

BPCREF produces an output file that contains: 

• An ordered and cross-referenced list of line nvimbers and variables in the 
translated image and the line numbers on which they are referenced 

• A list of line numbers and variables whose use is questionable 

• A statistical summary 

If you include the source file in your listing, it is printed at the beginning of 
the output file. 

Figure 6-1 shows a cross-reference listing of the octal-to-decimal conver¬ 
sion program used in the debugging example. (The bug was not corrected.) 
The following command was used to produce this listing: 

BPCREF coMMand? OCTDEC/WIDTH:72 
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The /WIDTH switch set the listing’s width to 72 columns. BPCREF placed 
the output in the file OCTDEC.CRF. 


Figure 6-1: Sample Cross-Reference Listing 


Header Line 


Cross Reference Listins of OCTDEC on 25-Aus-81 at 02:13 PM Pase 1 


m 

200 

300 

500 

900 


n 

600 

200 




« 

900 

100 




n 327B7 

600 

910 



DX 


300e 

aoo 

4000 

500 

ERL 


900 

910 



ERR 


910 




LX 


2006 

200 

300 


OX 


300B 

3000 

400 


S$ 


2000 

200 

300 

900 

VI 


3000 

300 

300 

400 

ZI 


3000 

300 

400 



8 Variables 

33 

References 


4006 


400 


► Cross-Reference 
Table 


15 Statements 


52 Name bxtes 
8 Total time 


150 Code bxtes 
4 CPU time 


-Mo rds 

Rese rued 

Used 

Free 

Data 

2.41 

1.37 

1.05 

Code 

• 59 

♦ 24 

.34 

Total 

3.00 

1.61 

1.39 


» Statistical Data 


The following sections describe each part of the listing. 

6.6.2.1 Header Line 

Each page of the output file has a header line that contains the translated 
program name, the current date and time of day, and a page number. Use 
the /NOHEADER switch to omit this line. 

6.6.2.2 Cross-Reference Table 

A cross-reference table of line numbers and variables is printed under the 
header line. Lines that start with a number sign (#) show references to line 
numbers made in the program. If no lines in the program reference other 
lines, this information is omitted. 

For example: 

• 200 300 500 900 

This line means that line number 200 is referenced in lines 300, 500, and 
900 of the OCTDEC program. Each of these lines contains a GOTO 200 
statement. 
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BPCREF prints cross-references to variables below the cross-references to 
line numbers. Each line consists of a variable name followed by one or more 
line numbers. The following codes (printed after line numbers) show the 
kind of references to variables: 

@ Destructive reference The reference to the variable on the line 

changed the value of the variable. 

• Definition A DIM statement or function defines the 

variable. 

For example: 

DZ 3000 400 4000 500 

This line means that the variable D% is referenced once in lines 300 and 
500 and twice in line 400. The value of D% changes in references marked 
with the @ symbol. 

6.6.2.3 Statistical Data 

The last part of BPCREF’s output, the statistical data, includes: 

• The number of variables in the code 

• The number of references to line numbers and variables 

• The number of statements in the code 

• The number of bytes needed to store variable definitions (name bytes) 

• The number of internal code elements (code bytes) 

• The elapsed and processor time (in seconds) used to create the output 

BPCREF also prints the size (in K words) of the program’s data and code 
areas, and the amount of memory reserved, actually used, and free for 
program expansion. 

6.6.2.4 Optional List of Suspect Line Numbers and Variables 

BPCREF determines, by cross-checking references to variables, whether a 
variable may be incorrectly referenced (never read, never written, never 
defined) and prints a list of these variables. The optional list of suspect line 
numbers and variables is introduced by the line: 

Please checK that the following variables have been referenced properly: 

This list points out possible typing errors in the source code. Note that 
BPCREF cannot logically analyze the program but can find simple typing 
and logic errors. 
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BPCREF finds no suspect line numbers or variables in the octal-to-decimal 
conversion program. However, the following program contains t 3 rping and 
logic errors that BPCREF can find. Line 200 references line 90, which 
does not exist, and two variable names, RADIUS and VOLUME, are 
misspelled. Because VOLUME is misspelled, its value is not calculated. A 
cross-reference listing that shows the suspect line niunbers and variables 
follows the program text. 


100 EXTEND 

200 DN ERROR GOTO 90 ! Error here 

300 INPUT "Radius”: RADIUS 
400 AREA = PI # RADIUS * 2.0 

500 VOLUEE = PI * RADIAS * 3.0 ! Errors here 

BOO PRINT "Area =": AREA! Uolutne VOLUME 

700 GOTO 300 
999 END 


Cross Referenoe Listins of DEMO on 25-Ausr-Sl at 02:30 PM Pade 1 


« 90 

200 


m 300 

700 


AREA 

4000 

600 

PI 

400 

500 

RADIAS 

500 


RADIUS 

3000 

400 

VOLUEE 

5000 


VOLUME 

600 



Please check that the following variables have been referenced properly; 
m 90 RADIAS VOLUEE VOLUME 


6.6.2.5 Global and Local Listings 

Global and local listings let you divide a program into two regions and 
print listings of variable references that indicate whether the reference is 
inside one region (local) or common to both (global). Such listings are useful 
if you plan to segment the program into chainable modules or convert the 
program to BASIC—PLUS-2. 

To request a global or local listing, use the global (/GL and /GH) or local 
(/LL and /LH) switches on the BPCREF command line. Global and local 
listings follow the full cross-reference listing. Each global or local listing 
you request appears on a separate page. Statistical information is printed 
after global and local listings. (If you want only a local or global reference 
listing, specify the /NOCREF switch to omit the full reference listing.) 

You can combine the global and local switches to get a listing of both types 
of references. For example: 

BPCREF coMMand? DCTDEC/GL 1 300/GH;400/LL;300/LH;400/W;72 
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This command adds the following information to the seimple listing of the 
octal-to-decimal conversion program: 


Cross Reference Listins of OCTDEC on 25-Aus-81 at 02sl9 PM Pase 2 
Global ranse is 300 to 400 

m 

Dt 
LZ 

S« 


This global listing means that line number 200 and the variables D%, L%, 
and S$ are referenced both inside and outside the global range, line 
numbers 300 through 400 in the program. References marked with the @ 
symbol are destructive. All other variables in lines 300 through 400 are 
referenced only inside the global range. 


300 

500 

900 


3000 

400 

400© 

500 

2000 

200 

300 


2000 

200 

300 

900 


Cross Reference ListinS of OCTDEC on 25-Au9-Bl at 02sl9 PM PaSe.3 




Local rantfe 

is 300 

to 400 

OZ 

3000 

3000 400 



oz 

3000 

300 300 

400 

4009 400 

zz 

3000 

300 400 




This local listing means that the variables 0%, V%, and Z% are referenced 
only inside the local range 300 through 400. References marked with the @ 
symbol are destructive. No line numbers are locally referenced in this 
rsinge. 

When more than one global or local switch of the same boundary type 
appear on the command line, BPCREF uses the last specification. For 
example: 

5PCREF coMMand? OCTDEC/GL:30/GL:20 


BPCREF uses line number 20 as the global reference lower boundary. 


6.6.3 Error Messages 

BPCREF displays error messages if you give incorrect input or if it finds 
fatal or unexpected conditions during processing. The messages are listed 
and described in Table 6-^. The first character of each message shows the 
severity of the error. The % character indicates a warning; BPCREF contin¬ 
ues processing but may not produce the results you expect. The ? character 
indicates a fatal error; BPCREF cannot finish processing and returns you to 
system command level. 


6-20 Immediate Mode and Program Debugging 




Table 6-4: BPCREF Error Messages 


7BPCREF version fatal error mmm at line nnn - text 

BPCREF or its auxiliary module BPCRFl encountered the condition described by 
RSTS/E error number mmm while executing an operation at line number nnn. 
BPCREF cannot continue. (Error numbers are listed in Appendix C.) 

?Can’t open filename - text 

BPCREF cannot access the named file because of the condition described by the 
RSTS/E error text. 

?Command error - text 

While processing the command you entered, BPCREF encountered the RSTS/E error 
described in the text. BPCREF prints a help message and redisplays the BPCREF 
Command? prompt. 

%Correct prime - nnn 

BPCREF has been incorrectly modified to change the variable table size. See your 
system manager. 

?Could not chain to filename - text 

BPCREF must chain to the auxiliary module BPCRFl described by filename. The 
RSTS/E error is printed in text. See your system manager. 

%Illegal width, minimum = 72 

You specified a value in the /WIDTH switch that is less than the allowed minimum. 
BPCREF sets the width to the minimiun (72 columns) and continues processing. 

?filename is not compiled BASIC-PLUS program 

The file indicated by filename is not a valid BASIC-PLUS translated image. 
BPCREF cannot process a source file, task image, or any other type of file. 

?Maximum memory exceeded 

Because of the high number (or great length) of variable names, the BPCREF varia¬ 
ble table overflowed. Subdivide the program and process each module separately. 

?filename must be on disk 

The file named in filename is not on a disk device. BPCREF processes only disk files. 
?Plea8e run BPCREF 

You tried to run the BPCRFl module, which is part of the BPCREF program. 
BPCRFl prints this message and returns you to system command level. 

%Reference table full 

An internal table is full. BPCREF continues processing but loses some data. Subdi¬ 
vide the program and process each module separately. 

%Unknown compiled code nn at line mm 

BPCREF encountered a BASIC-PLUS operation code (nn) that it did not recognize. 
BPCREF continues processing but it may lose some data or output incorrect data (for 
example, the program may miss a variable reference at this point). 

%Unknown switch(es), text 

You specified an undefined switch in a BPCREF command without the /QUEUE 
switch. BPCREF ignores the switch and continues processing. 

(continued on next page) 
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Table 6-4: BPCREF Error Messages (Cont.) 


%Unknown 8witch(es), text will be passed to queue manager 

You specified an undefined switch in a BPCREF command containing the /QUEUE 
switch, BPCREF passes the information in *'text” to the spooling program. 

%Variable table full 

BPCREF can process a maximum of 421 variables (plus line numbers used in GOTO 
and GOSUB statements). Decrease the number of variables in the program and try 
again, or subdivide the program and process each module separately. Note that the 
system manager can increase the maximum number of variables that BPCREF can 
process. 
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Chapter 7 

Building a Program 


This chapter describes the structure and format of BASIC-PLUS programs. 
It describes line numbers, statements, remarks, and comments, and 
explains the difference between EXTEND and NOEXTEND format. 

7.1 Sample BASIC-PLUS Program 

The program in Figure 7-1 is written in the BASIC-PLUS language, tising 
EXTEND format. It illustrates the syntax of the language, the format of 
statements, and the appearance of terminal output. 

The program calculates totals from random dice rolls. When you run the 
program, you enter the number of dice per roll and the number of rolls. 

7.2 Parts of a Program 

A BASIC—PLUS program consists of lines of statements that contain 
instructions. Each line starts with a line number. 

7.2.1 Line Numbers 

Line numbers, which cem range from 1 to 32767, specify the order in which 
statements aire to be executed. You can enter lines in any order when you 
type the program into the system; BASIC-PLUS always keeps the program 
in order by line number. 
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Figure 7-1: Sample BASIG-PLUS Program 


LISTNH 

50 EXTEND 

100 RANDOMIZE & 

ITHIS IS A RANDOM DICE ROLL ROUTINE & 

!THE USER CAN SPECIFY HOW MANY DICE TO BE IN 8c 
lEACH ROLL AND HOW MANY ROLLS ARE TO BE MADE* 8: 

IWHETHER TO PRINT THE TOTAL OF EACH ROLL IS ALSO 8c 
(UNDER USER CONTROL 

no PRINT 'THIS PROGRAM GIVES RANDOM DICE ROLLS' 8c 
\ PRINT 'HOW MANY DIES IN EACH ROLL'? 8c 
\ INPUT N &C 

\ PRINT 'HOW MANY ROLLS'; & 

\ INPUT D 8c 

\ PRINT 'IF YOU WANT THE TOTAL OF EACH ROLL# TYPE Y' i 8c 
\ INPUT R$ 8c 
\ PRINT 

120 FOR J = 1 TO D 8. 

\ PRINT 'the';n; 'dies of roll';j;'ares'; 

130 FOR I = 1 TO N 8c 

\ LET AZ=(INT(B*RND) + 1) 8c 
\ LET BX=AZ -I- BZ 8c 
\ PRINT AX; 8c 
\ NEXT I 

140 IF R$ - 'Y' THEN PRINT '---TOTAL OF ROLL =';BX 
150 PRINT & 

\ LET BX = OX 8c 
\ NEXT J 
327B7 END 


Ready 


runnh 

THIS PROGRAM GIVES RANDOM DICE ROLLS 
HOW MANY DIES IN EACH ROLL? 5 
HOW MANY ROLLS? 3 

IF YOU WANT THE TOTAL OF EACH ROLL# TYPE Y? Y 

THE 5 DIES OF ROLL 1 ARE: 42443 ---TOTAL OF ROLL = 17 

THE 5 DIES OF ROLL 2 ARE: B 5 1 4 5 ---TOTAL OF ROLL = 21 

THE 5 DIES OF ROLL 3 ARE: 5 5 4 B 5 ---TOTAL OF ROLL = 25 

Ready 
RUNNH 

THIS PROGRAM GIVES RANDOM DICE ROLLS 
HOW MANY DIES IN EACH ROLL? 2 
HOW MANY ROLLS? 5 

IF YOU WANT THE TOTAL OF EACH ROLL# TYPE Y? N 


THE 

2 

DIES 

OF 

ROLL 

1 

ARE: 

2 

3 

THE 

2 

DIES 

OF 

ROLL 

2 

ARE: 

4 

4 

THE 

2 

DIES 

OF 

ROLL 

3 

ARE: 

4 

3 

THE 

2 

DIES 

OF 

ROLL 

4 

ARE: 

3 

S 

THE 

2 

DIES 

OF 

ROLL 

5 

ARE: 

3 

5 


Ready 
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Line numbers also: 


• Let you change the order in which statements are executed. You can 
include statements in a program to make execution branch or loop around 
parts of the program. (See the sections on the (SOTO, GOSUB, and 
IF—THEN statements in Chapter 9 for more information.) 

• Help you debug and edit programs. BASIC—PLUS debugg in g features let 
you stop execution at any line in a program, examine variables and mod¬ 
ify code, and then resume execution at any line. BASIC-PLUS editing 
features let you change one or more program lines without affecting 
the rest of the program. (See Chapters 5 and 6 in Part I for more 
information.) 

When you first write a program, number lines in increments of 10 or more. 
This practice lets you insert new lines when debugging or enhancing the 
program. You may also want to start numbering at line 100 so you can 
enter a large amoimt of code at the beginning of your progrsim at a later 
time. 

7.2.2 Statements 

You give instructions to BASIC-PLUS by writing statements. One or more 
BASICJ—PLUS statements follows each line number in a program. The 
first word of each statement, called a keyword, identifies it, tellin g 
BASI(3-PLUS which operation to perform and how to treat the rest of the 
statement. 

The rest of a BASIC—PLUS statement consists of operators and operands. 
An o^rator is a symbol that specifies the action to perform (such as + for 
addition); an operand is the data on which to perform the action. Operands 
can be constants, which have fixed values, or variables, whose values can 
change during program execution. When you write statements, you com¬ 
bine operators and operands into expressions, which are groups of symbols 
that BASIC—PLUS evaluates. Chapter 8 describes keywords, constants, 
variables, operators, and expressions in more detail. 

The sample program contains several different types of BASIC-PLUS 
statements, which in turn contain expressions composed of constants, vari¬ 
ables, and operators. Consider these statements from line 130 of the sample 
program: 

LET 6*=A* + BZ 
PRINT AX! 

The first statement, called an assignment statement, assigns a value to the 
variable B%. The part of the statement to the right of the equals sign is an 
arithmetic expression. It is composed of the variables A% and B% separated 
by a plus sign, which specifies addition. During program execution, 
BASICJ—PLUS evaluates this expression by adding the current values of 
A% and B% and then eissigns their sum to B%. 
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The next statement, a PRINT statement, prints the current value of the 
variable A% on the terminal. A% is the operand in this PRINT statement. 

Other PRINT statements in the sample program have text as an operand. 
For example: 

PRINT 'THIS PROGRAM GIVES RANDOM DICE ROLLS' 

This statement prints on the terminal: 

THIS PROGRAM GIVES RANDOM DICE ROLLS 

You must enclose text in quotation marks when you write this kind of 
PRINT statement. 

7.3 Line and Statement Formats 

There are two types of lines in a BASIC-PLUS program: program lines and 
terminal lines, also called text lines. Program lines always have a line 
number. You can write a complete program line on one terminal line or you 
ran continue a program line over several terminal lines. For example: 

150 PRINT 8<® 

\ B* = 0 8.® 

\ NEXT J® 

32767 END® 

Line 160 is a program line that is continued over three terminal lines. The 
first two terminal lines in line 150 end with an ampersand (&) followed by 
the RETURN key. This sequence indicates that the program line is contin¬ 
ued on the next terminal line. The last terminal line in line 150 ends with 
just the RETURN key; this indicates the end of the program line. Line 
32767 is a complete program line on One terminal line. 

The simplest way to format a program is to place a single statement on 
each program line. However, BASIC—PLUS lets you place multiple state¬ 
ments on a single program line, and it also lets you continue a single 
statement on successive terminal lines. 

7.3.1 Multi-Statement Lines 

To write multiple statements on a single program line, end each statement 
(except the last) with a backslash (\). 

The following examples show two ways to write a program line that con¬ 
tains three statements. In both examples, all three statements (LET, 
PRINT, and IF-THEN) are part of line 20 of the program. The first exam¬ 
ple uses a single terminal line; the second uses three terminal lines: 

20 LET X = X+1.\ PRINT X»Y»Z\ IF Y = 2. THEN GOTO 10® 

20 LET X = X+1. &® 

\ PRINT X»Y*Z 8.® 

\ IF Y = 2. THEN GOTO 10® 


7-4 Building a Program 




Writing each statement on a separate terminal line makes your program 
easier to read. In addition, if you use EXTEND mode, you can place a 
comment after each statement (see Section 7.4). 

7.3.2 Multi-Line Statements 

You continue a single BASIC-PLUS statement on successive terminal lines 
by ending each terminal line with the LINE FEED key (in both EXTEND 
and NOEXTEND modes) or an ampersemd (&) character followed by the 
RETURN key (in EXTEND mode only). The ampersand/RETURN key 
combination is preferred. For example: 

10 LET W7=(l.l-X4*3>*(Z-A/ffi 
<A-B)-17)® 

10 LET W7=(W-XA*3)*(Z-A/ 8.® 

(A-B)-17)® 

These statements are the same as: 

10 LET M7=<W-Xfl*3)*(Z-A/<A-B»-17)® 


You cannot separate parts of a language keyword, a constant, a variable 
name, or a line number when you continue a statement. The following 
examples show correct and incorrect statement continuation. In the exam¬ 
ples, A1 is a variable name and 100 is a line number. The first incorrect 
example inserts a break in the variable name; the second incorrect example 
inserts a break in the line number. 

Correct 

10 IF A1=0. 8c® 

THEN GOTO 100 


Incorrect 

10 IF A 8c® 

1=0. THEN GOTO 100® 

?IlIe9al conditional clause 

10 IF A1=04 then goto 1 8c(E) 

00 

?Modifier error at line 10 

Any illegal statement produces an error message. 


BASIC—PLUS recognizes several phrases as single keywords that cannot be 
broken by a line continuation. These phrases are; 


GOTO 
GO SUB 

ON ERROR GO TO 
INPUT UNE 
NO EXTEND 


AS FILE 

FOR INPUT AS FILE 
FOR OUTPUT AS FILE 
FILE SIZE 


MAT READ 
MAT PRINT 
MAT INPUT 
MAT LET 
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Note that besides indicating continviation, the ampersand/RETURN key 
also signals the end of a comment. The LINE FEED key indicates continua¬ 
tion only; it does not signal the end of a comment. See Section 7.4 for more 
information. 

7.3.3 Spaces and Tabs 

Spaces and tabs make programs easier to read. Use spaces between line 
numbers and statements. Also use spaces between parts of a statement. For 
example: 

10 LET X = Y»2 + 1 
10 LET X=Y*2+1 


These two LET statements are both valid, but the first is easier to read 
than the second. 

You use spaces differently in EXTEND and NOEXTEND mode formats. 
See Section 7.5.2 for details. 

The following example shows use of tabs: 


2000 FOR K=1 TO 3 

2010 FOR 1=1 TO 10 

2020 FOR J=1 TO 10 

2030 A(I»J) = K/(I+J-1)+A<I»J) 

2040 NEXT J 

2050 NEXT I 

2060 NEXT K 

32767 END 


This example shows how tabs can make a program with nested FOR loops 
easier to read. FOR loops are used in programs to perform operations repet¬ 
itively; each FOR loop starts with a FOR statement and ends with a NEXT 
statement. Nesting means placing one FOR loop inside another FOR loop. 
(FOR loops and nesting are explained in Chapter 9.) 

7.4 Remarks and Comments 

It is good program m ing practice to document a program as you develop it 
by including remarks and comments in the program. For example, the 
following kinds of information are useful to someone reading or modifying a 
program: 

• The name and purpose of the program 

• How to use the program 

• How certain parts of the program work 

• Expected results at various points in the program 
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You can insert this kind of information into a program with the REM 
statement and the exclamation point (!). Messages in REM statements are 
called remarks; those after the exclamation point are called comments. For 
example, line 100 of the program shown in Figure 7-1 contains several 
comments that describe the program: 

100 RANDOMIZE & 

! THIS IS A RANDOM DICE ROLL ROUTINE & 

! THE USER CAN SPECIFY HOW MANY DICE TO BE IN & 

! EACH ROLL AND HOW MANY ROLLS ARE TO BE MADE* fic 
! WHETHER TO PRINT THE TOTAL OF EACH ROLL IS ALSO & 

! UNDER USER CONTROL 

Remarks and comments are printed when you list your program but they 
do not affect program execution. They can, however, affect program size. 

REM statements can contain any printing characters on the keyboard. 
In EXTEND mode, the word REM must be followed by a space or tab. 
BASIC-PLUS ignores, but includes in the line, anything that follows the 
letters REM. You can use the line number of a REM statement in a GOTO 
or GOSUB statement as the destination of a branch in program execution 
(see Sections 9.3 and 9.9). Typical REM statements are: 

10 REM - THIS PROGRAM COMPUTES THE 

11 REM - ROOTS OF A QUADRATIC EQUATION 

Comments can be placed on the same line as statements. The exclamation 
point (!) ends the executable part of the line and begins the comment part of 
the line. When a line begins with an exclamation point, BASIC-PLUS 
treats the entire line as a comment. In the next example, BASIC-PLUS 
executes the LET statement on line 125 and the PRINT statement on line 
130 but does not execute the PRINT statement on line 140: 

125 LET A = 2+Q«S0R(C) !SET A EQUAL TO INITIAL VALUE 
130 PRINT A/2 + 1 IPRINT SECOND CALCULATED VALUE 
140 !COMMENT \ PRINT "THIS LINE IS A COMMENT" 

In every statement except the DATA statement, BASIC-PLUS ignores 
everything on the line after the exclamation point. An exclamation point 
must not appear on the same program line as a DATA statement unless it 
is one of the items in the DATA statement list. The exclamation point 
becomes part of the data. (See Chapter 9 for a description of the DATA 
statement.) 

The following examples show four ways of putting the same information on 
two lines. Lines 10 and 11 are REM statements. Line 20 is one REM state¬ 
ment broken into two lines with the LINE FEED key. Line 30 is one com¬ 
ment (begun with a ”!”) broken into two lines with the LINE FEED key. 
Line 40 is one comment broken into two lines with ampersand/RETURN, 
which is legal only in EXTEND mode. 
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10 REM THIS PROGRAM COMPUTES THE 

11 REM ROOTS OF A QUADRATIC EQUATION 

20 REM THIS PROGRAM COMPUTES THE © 
ROOTS OF A QUADRATIC EQUATION 

30 ! THIS PROGRAM COMPUTES THE @ 
ROOTS OF A QUADRATIC EQUATION 

40 !THIS PROGRAM COMPUTES THE 8.® 
•ROOTS OF A QUADRATIC EQUATION 


Note that besides indicating continuation, the ampersand/RETURN key 
also signals the end of a comment. This EXTEND mode feature lets you 
alternate comments and code over several text lines. For example; 

10 EXTEND 

20 PRINT "This example" IComment &® 

\ PRINT "illustrates" IComment 8.® 

\ PRINT "how comments and statements" IComment 8i® 

\ PRINT "can be used with 8./RETURN in EXTEND mode."® 

30 END 


When you run this program, it prints: 

This example 
i 1 lust rates 

how comments and statements 

can be used with Si/RETURN in EXTEND mode. 


BASIC-PLUS begins to recognize characters as statements instead of com¬ 
ments when it encounters the ampersand/carriage return. Thus, when you 
use this sequence to continue a comment on the next terminal line, you 
must start the continuation line with an exclamation point. Otherwise, the 
line will be interpreted as an executable statement. For example; 

10 EXTEND 

20 I THIS PROGRAM COMPUTES THE 8.® 

I ROOTS OF A QUADRATIC EQUATION 8.® 

PRINT "ENTER THREE COEFFICIENTS" ® 

RUNNH 

ENTER THREE COEFFICIENTS 


Ready 


Unlike the ampersand/RETURN key, the LINE FEED key does not signal 
the end of a comment. Thus, if you use the LINE FEED key for continua¬ 
tion instead of the ampersand/RETURN key (in either EXTEND or 
NOEXTEND mode), BASIC-PLUS treats all characters between the excla¬ 
mation point and the end of the program line as a comment. For example; 

10 PRINT "This is a statement." IComment© 

\ PRINT “but the rest of this program line is a comment." 

20 END 
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When you run this program, only the first PRINT statement is executed. 
Thus, the program prints; 

This is a statewentt 

7.5 EXTEND and NOEXTEND Modes 

BASIC-PLUS has two modes of operation: EXTEND and NOEXTEND. 
The mode you work in determines which BASIC-PLUS features you can 
use and how you must format your programs. 

The examples in this manual are written to execute in EXTEND mode, the 
recommended mode of operation. This section explains how to change 
modes and describes the differences between EXTEND and NOEXTEND 
program formats. 

7.5.1 Changing Modes 

The system manager determines which mode is the default on each system. 
However, you can change modes at any time by using EXTEND or 
NOEXTEND as a command or a program statement. Enter EXTEND or 
NOEXTEND as a command to set the mode for the current terminal ses¬ 
sion; use EXTEND or NOEXTEND as the first statement in a program to 
set the mode for the current program. 

The following examples show use of EXTEND as a command and a state¬ 
ment. These examples assume you are working on a system where 
NOEXTEND is the default mode. 

Here the EXTEND command puts you in EXTEND mode: 

EXTEND 

Ready 

You stay in EXTEND mode until you either: 

• Enter the NOEXTEND co mm and 

• Use the NOEXTEND statement in your current program 

• Run an executable (not a source) program 

• Use a CCL or DCL com m and 

• Switch to another keyboard monitor 

• Log out 

In the next example, you use EXTEND as a program statement: 

NEM PROGl 
Ready 

100 EXTEND 
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You are in EXTEND mode while this program is your cvirrent program. 
However, the system puts you back in NOEXTEND mode if you run 
another program (with RUN, a CCL command, or a DCL command), create 
a program with NEW, or retrieve an existing program with OLD. 


While BASIC-PLUS allows you to change modes within a program, this 
practice is not recommended. Write an entire program in either EXTEND 
or NOEXTEND mode — the program will be much easier to debug and 
maintain. 


It is recommended that you work in EXTEND mode. You can use features 
not available in NOEXTEND mode, such as long variable names. In addi¬ 
tion, programs written in EXTEND format are more compatible with other 
DIGITAL versions of BASIC. However, EXTEND format rules are more 
stringent than NOEXTEND format rules. 


7.5.2 EXTEND and NOEXTEND Program Formats 

Figures 7—2 and 7-3 show the differences between EXTEND and 
NOEXTEND format. Figure 7-2 is line 300 of the program OCTDEC.BAS 
written in NOEXTEND format; Figure 7-3 is the same line written in 
EXTEND format. 


Figure 7—2: NOEXTEND Format 


300 OZ = -IX \ DX = OX 

\ FOR ZX = LX TD IX STEP -IX 
\ OX = OX + IX 
\ MX = ASCII (RIGHT(S*>ZX>> 

\ IF MX < aSX OR MX > 55X THEN 
PRINT 'INMALID INPUT' 

\ G0T0200 

I initialize order and accumulator for each ditfit 
I from the low order to the hi^h order# 

I inc rement order# 

! picK UP next di^it# 

I if out of ranges ask for more input 
I and print message* 


Figure 7—3: EXTEND Format 


300 ORDERX = -iX 

\ ACCUMULATORX = OX 
\ FOR ZX = LNGTHX TO IX STEP -IX 


\ ORDERX = ORDERX + IX 
\ MALUEX = ASCII(RIGHT(S$»ZX>) 

\ IF MALUEX < ASX OR MALUEX > 55X THEN 
PRINT "INMALID INPUT" 

\ GOTO 200 


! initialize order & 

! and accumulator & 

! for each didit from & 
! the low order to & 

! the hish order & 

! increment order & 

! pick UP next disit & 

! if out of ranSe: & 

! print messase & 

I ask for more input & 
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EXTEND and NOEXTEND formats differ in their: 


• Rules for naming variables and functions. (A function is a named set of 
instructions.) 

• Use of spaces and tabs. 

• Line continuation. 

• Placement of comments. 


7.5.2.1 Variable and Function Names 


In EXTEND format, a variable or function name consists of a letter fol¬ 
lowed by 0 to 29 characters from the set: 


Letters 

Digits 

Period 


(A,B,...,Z and a,b,...,z) 

( 0 , 1 ...., 9 ) 

(.) 


Some examples are RECORD.NUMBER, BIG47, J.IO. If you use an exist¬ 
ing BASIC-PLUS keyword or built-in function name, BASIC-PLUS 
retm-ns the error "%Illegal symbol.” (Appendix A lists all BASIC-PLUS 
keywords.) 

In NOEXTEND format a variable or function name consists of a letter 
optionally followed by a digit. Some examples are A, Al, B4. 

Note that in both EXTEND and NOEXTEND formats, you add a percent 
(%) sign suffix to the variable name to indicate an integer variable; you add 
a dollar ($) sign suffix to the variable name to indicate a string variable. 
For example: 


AX RECORD.NUHBERX 

A« ADDRESS* 


See Section 8.3.2 for more information. 

7.5.2.2 Spaces and Tabs 

Spaces and tabs are significant in EXTEND format but not in NOEXTEND 
format. Thus, the following statements are illegal in EXTEND mode: 

10G0T0200 This statement needs a space between line number 10 

and GOTO and between GOTO and line number 200. 
Write the statement as "10 GOTO 200”. 

10 L ETX = Y*2 + 1 The keyword LET contains embedded spaces that must 

be removed. In addition, a space must be inserted 
between the ke3nvord LET and the variable name X. 
Write the statement as: "10 LET X = Y*2 + 1”. 

The next statement is valid in both EXTEND and NOEXTEND mode but 
has a different action in each: 

10 LETX « Y*2 + 1 
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In EXTEND mode, this statement assigns the value of (Y*2 + 1) to the 
variable named LETX. In NOEXTEND mode this statement assigns the 
value of (Y*2 + 1) to the variable named X. 

7.5.2.3 Continuation Lines 

In EXTEND format you can continue a program line onto the next terminal 
or text line with either the LINE FEED key or the ampersand/RETURN 
key combination. The ampersand/RETURN key combination is the pre¬ 
ferred method because: 

• It is compatible with BASIC-PLUS-2 

• It allows you to alternate comments and statements on a program line 
that continues over several text lines, as shown in Figure 7-3 

In NOEXTEND format you must xise the LINE FEED key to continue a 
program line onto the next terminal or text line. 

7.5.2.4 Comments 

When you write a program line on one terminal line, the rules for placing 
comments and statements on the same line are the same in EXTEND and 
NOEXTEND modes. You can place a comment after a statement, but you 
csumot place a statement after a comment. 

When you continue a program line over two or more text lines, however, 
the rules for using comments differ depending on whether you indicate 
continuation with the ampersand/RETURN key combination, legal only in 
EXTEND mode, or the LINE FEED key, legal in both EXTEND and 
NOEXTEND modes. 

You can alternate comments and statements on the same line, as shown in 
Figfure 7—3, only if you use the ampersand/RETURN key combination (not 
the LINE FEED key) to indicate continuation. See Section 7.4 for details. 
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Chapter 8 

Building Statements 


Chapter 7 introduced you to BASIC-PLUS statements; this chapter 
describes the elements that statements are composed of: ke3^ords, data, 
and expressions. In addition, this chapter summarizes the BASIC—PLUS 
character set, which you use to specify these elements. 

8.1 BASIC-PLUS Character Set 

BASIC-PLUS uses the lull ASCII character set. This set includes: 

• The letters A through Z, in both upper- and lowercase 

• The digits 0 through 9 

• Special characters, such as the period (.) and the asterisk (*) 

Appendix D lists the complete BASIC—PLUS character set. The appendix 
includes special symbols and keys and lists ASCII character codes. 

BASIC-PLUS treats upper- and lowercase letters the same except in string 
data and ignores characters in REMARK statements and comments. 

8.2 Keywords 

The BASIC—PLUS language reserves a set of words and phrases for its own 
use. These words and phrases are called ke}rwords. 

BASIC-PLUS keywords include: 

• Statement names, such as PRINT and LET 

• Built-in function names, such as SIN and TAN 

• Built-in variable names, such as ERR and STATUS 

• Option names, such as MODE and FILESIZE 
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You cannot use BASIC—PLUS keywords as names for your own variables or 
functions imless you modify them. For example, you cannot name a vsu'ia- 
ble FILESIZE, but you can name it FILE.SIZE. Appendix A contains a 
complete list of BASIC—PLUS keywords. 


8.3 Data 


BASIC-PLUS has three types of data: 

• Real data 

• Integer data 

• String data 

Real data and integer data are numeric data; string data are character 
data. BASIC-PLUS stores the three types of data using different internal 
formats. 

Real data are stored as floating-point numbers. (The term floating-point 
refers to the decimal point.) Unlike integers, which are whole numbers, 
real numbers can have a fractional part. You can specify a real number in 
decimal format or in exponential format. Both formats are explained in 
Section 8.3.1.1. 

Floating-point numbers are stored in memory in either a two-word or four- 
word format, depending on which math package you have on your system. 
The two-word format, called single-precision, provides six significant digits; 
the four-word format, called double-precision, provides fifteen significant 
digits. Floating-point numbers, and thus real data, can range in value from 
10 "-38 to 10 "38. 

By default, BASIC-PLUS prints numbers with more than six digits in 
exponential or E format. BASIC—PLUS prints a minus sign after the E if 
the exponent is negative (lE-09) and prints a space after the E if 
the exponent is positive (IE 09). See Section 8.3.1.1 for a description of 
E format. 

Integer data are whole numbers without decimal points. Integers are stored 
in memory in binary form. Each integer uses one word of memory. 
BASIC-PLUS converts the binary integer to a decimal number before 
returning its value to you. Integers can range in value from —32768 to 
32767. 

String data are stored as groups of ASCII chfiracters. BASIC-PLUS treats 
all the characters in a string as a unit. Each character in a string uses one 
b 3 de (half a word) of memory storage. BASIC-PLUS keeps track of the 
length of a string as well as the characters it contains. 

Table 8-1 summarizes the three data t 3 ^es. 
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Table 8-1: BASIC-PLUS Data Types 


Data Type 

Internal Format 

Value Range 

Real 

Two-word or fom-word 
floating-point 

10 "-38 to 10 "38 

Integer 

One-word binary 

-32768 to 32767 

String 

ASCII format; one byte 

0 to 32767 characters 


(half-word) per character 

per string 


All three types of data can be represented as constants or variables. Con¬ 
stants keep the same value throughout a program and are specified in the 
program itself. Variables can change in value during program execution. 
When you write expressions, you use constants and variables as operands. 
The following sections describe constants and variables in more detail. 

8.3.1 Constants 

BASIC—PLUS has real, integer, and string constants. 

8.3.1.1 Real Constants 

A real constant is one or more decimal digits, either positive or negative, 
with an optional decimal point. For example: 


+ 2 . 

-3.675 

1234.56 

-123456 

-.000001 


These numbers are in decimal format. Although the decimal point is 
optional, its use is recommended because it avoids unnecessary data 
conversions and makes your program easier to read. 

You can input large and small numbers using exponential format. This 
mathematical shorthand uses the format: 


+ 


number E 



n 


where: 


+ or - is the number’s sign. The plus sign is optional, but the minus 
sign for a negative number is required. 

number is the number carried to a maximum of six decimal places 
for single-precision or fifteen decimal places for double¬ 
precision. 
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E stands for ’’multiplied by 10 to the power of.” 

+ or- is the exponent’s sign. The plus sign is optional, but the 
minus sign is required. 

n is an integer constant (the power of 10). It can be zero but not 

blank. 


For example: 

>000123456 can be written as 123456E-9 

1234560000# can be written as 123456E4 

-12345678900. can be written as -1.23456789E10 

The E format is flexible; you can write .001 as IE—3, .OlE-1, or lOOEJ-6. 

Note that, by default, BASIC—PLUS prints numbers with fewer than six 
digits in decimal format and munbers with more than six digits in exponen¬ 
tial format. 

8.3.1.2 Integer Constants 

An integer constant is a whole number followed by a percent sign. For 
example: 

29Z -8X 

3432X U 

12345Z 205Z 

Integer constants can range in value from -32767% to 32767%. Because the 
largest integer has only five digits, BASIC-PLUS always prints integers in 
decimal format. 

8.3.1.3 String Constants 

A string constant is a series of ASCII characters enclosed in single or 
double quotation marks (called the string delimiter). Some examples of 
string constants are: 

"THE RECORD NUM6ER DOES NOT EXIST" 

'THIS PROGRAM GIVES RANDOM DICE ROLLS' 

*'4 Baymeadow Driue" 

Characters in string constants can be letters, numbers, spaces, tabs, or any 
ASCII character except the string delimiter. BASIC-PLUS prints every 
character between delimiters exactly as you type it in the source program, 
including upper- and lowercase letters; tabs; special characters; and lead¬ 
ing, trailing, and embedded spaces. For example, these two string constants 
are different: 

"END-OF-FILE REACHED" 

" END-OF-FILE REACHED 
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BASIC-PLUS does not print the delimiting quotation marks when execut¬ 
ing the program. For example: 

10 PRINT ’'END«OF-FILE REACHED” 

20 END 
RUNNH 

END-OF-FILE REACHED 

To print quotation marks, enclose single quotation marks inside double 
marks or vice versa. For example: 

10 PRINT 'FAILURE CONDITION: "RECORD LENGTH"' 

20 END 
RUNNH 

FAILURE CONDITION: "RECORD LENGTH" 

You cannot mix single and double quotation marks. The following is not a 
valid string: 

"Quotation marKs do not match' 

BASIC-PLUS lets you omit the second quotation mark but not the first. 
This string is valid: 

"Second quotation mark missina 

But this string is not valid: 

First quotation mark missins" 

A string can contain up to 32767 characters but is limited by the amount of 
available memory. You cannot use the LINE FEED key or the &/RETURN 
key combination to type a string on two or more terminal lines. To create a 
string longer than a terminal line, use string concatenation, described in 
Section 8.4.2, or other string operations described in Chapter 10. You can 
also save long strings in disk files. 

8.3.2 Variables 

You specify constants as numbers or quoted strings; you specify variables 
by name. A variable reserves a location in the computer’s memory. The 
variable names the location and lets you assign any legal number or string 
to it. Each memory location can hold only one value at a time. 

Depending on the operations you specify, the value of a variable can change 
as each statement in your program is executed. BASIC-PLUS uses the 
most recently assigned value when performing calculations. The value 
remains the same until another statement assigns a new value to the 
variable. 
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BASIC-PLUS sets all numeric variables equal to 0 and all string variables 
equal to the null (empty) string before program execution. Thus, you need 
to assign an initial value to a variable only when you want a different 
value. However, it is always good programming practice to assign initial 
values to variables at the beginning of the program. 

BASIC!-PLUS has real, integer, and string variables. The two types of 
numeric variables, real and integer, reserve locations for numeric values. 
String variables reserve locations for string values. All t 3 rpes of variables 
can have subscripts. Subscripted variables break up memory into compart¬ 
ments and let you store data in arrays. (See Chapter 9.) 

8.3.2.1 Naming Variables 

All variable names must start with a letter and can be followed by up to 29 
letters, digits, or periods (in EXTEND mode) or a single digit (in 
NOEXTEND mode). Variable names cannot contain embedded spaces. 

You add a percent sign (%) suffix to the variable name to define an integer 
variable; you add a dollar sign ($) suffix to the variable name to define a 
string variable. Real variable names have no suffix. 

Note that variables with the same name but different suffixes are different 
variables. For example, if you use A and A% in the same program, 
BASIC-PLUS defines two variables: A, a real variable, and A%, an integer 
variable. The next three sections describe each type of variable. 

8.3.2.2 Real Variables 

A real variable is a named memory location that stores a real (floating¬ 
point) number. For example: 

C L...5 ID.NUMBER 

Ml BIG47 STORAGE.LOCATION.FOR.XX 

If you assign an integer constant to a real variable, BASIC—PLUS converts 
the integer to a real number. For example: 

10 LET A = lOX 
20 PRINT A 
30 END 
RUNNH 
10 


8.3.2.3 Integer Variables 

An integer variable is a named memory location that stores a whole num¬ 
ber. An integer variable name ends with a percent sign (%). For example: 

BZ C.8Z RECORD.NUMBERZ 

A3Z DBE7Z COUNTERZ 
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If you assign a real constant to an integer variable, BASIC-PLUS drops the 
fractional portion of the constant; it does not round to the nearest integer. 
For example: 

BX = 5.7 

BASIC-PLUS assigns the value 5 to the integer variable, not 6. 

Use integer variables, not real variables, for working vrith whole numbers 
in the range -32767 to 32767. Integers use less memory storage space than 
floating-point numbers and are more efficient for the computer to process. 

8.3.2.4 String Variables 

A string veiriable is a named memory location that stores a string value. A 
string variable name ends with a dollar sign ($). For example: 

A$ 112* EMPLOYEE.NAME* 

T..* L.6* tEXT* 

Strings have both value and length. BASIC-PLUS sets all string variables 
to a default length of zero when it translates your program. During pro¬ 
gram execution, however, the length of a character string associated with a 
string variable can vary from zero (a null or empty string) to 32767 charac¬ 
ters (including spaces). 

8.4 Expressions 

Expressions consist of operands (constants, variables, functions) separated 
by arithmetic, relational, or logical operators. Depending on the data t 3 T)es 
of the operands (real, integer, string), the three t 3 Tpes of operators produce: 

• Arithmetic expressions 

• String expressions 

• Relational expressions 

• Logical expressions 

Here are some examples of expressions: 

PI * RADIUS *2 Arithmetic Expression 

FILENAME* + + TYPE* String Expression 

A < B Relational Expression 

(A < B ) AND (B < C) Logical Expression 

Like a constant and a variable, an expression is a way to represent a value 
in BASIC—PLUS. When you use an expression in a statement, 
BASIC)—PLUS evaluates or "solves” it, using the same kinds of rules you do 
when you solve mathematical problems. After eval uati ng the expression, 
BASIC^PLUS uses the result in program execution. 
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In many BASIC—PLUS statements, you can specify either a constant, a 
variable, a function, or an expression. (Functions are described later in this 
manual.) The KILL statement, which deletes a file, is a good example. In 
Chapter 5, you learned how to use KILL as an immediate mode statement; 
KILL can also be used in a program. 

When you write a KILL statement, you specify the file to be deleted as a 
string. The string can be a string constant, a string variable, a string func¬ 
tion (see Chapter 10), or a string expression. For example: 

10 KILL “TAXES.DAT" String Constant 

20 KILL FILESPEC$ String Variable 

30 KILL FILENAME* + ".DAT" String Expression 


The string constant in line 10 specifies the file directly; BASIC—PLUS 
deletes TAXES.DAT every time this KILL statement is executed. 

The string variable in line 20 refers to a location where a file specification 
is stored. When this KILL statement is executed, BASIC-PLUS deletes the 
file whose file specification is ciurently stored in FILESPEC$. Depending 
on how the rest of the program is written, the contents of FILESPEC$ may 
differ each time the program is run or each time this KILL statement is 
executed during the same program run. 

The string expression in line 30 contains both a string variable and a string 
constant. When this KILL statement is executed, BASIC-PLUS evaluates 
the string expression to determine which file to delete. The plus ( -I- ) sign 
causes BASIC-PLUS to form a single string made up of the characters 
stored in the variable FILENAME$ followed by the characters ”.DAT”. 
BASIC-PLUS deletes the file specified by this string. Like line 20, this 
expression may cause a different file to be deleted each time the program 
is run or each time this KILL statement is executed during the same pro¬ 
gram run. 

Many statement descriptions in this meinual indicate that you must supply 
an expression. When you write these statements, you can use a constant, a 
variable, a function, or an expression. 

The following sections describe the four types of expressions in detail and 
explain how BASIC-PLUS evaluates them. 

8.4.1 Arithmetic Expressions 

Arithmetic expressions are real or integer operands separated by arithme¬ 
tic operators. These expressions tell BASIC—PLUS to add, subtract, multi¬ 
ply, or divide numbers or to raise a number to a power, which is called 
exponentiation. The five arithmetic operators are shown in Table 8-2. 
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Besides the circumflex (^), you can also use double asterisks («*) to denote 
exponentiation. However, the circumflex is preferred because it is the stan¬ 
dard BASIC-PLUS symbol for exponentiation. Use of the circumflex 
ensxires compatibility with other versions of BASIC. 


Table 8-2: Arithmetic Operators 


Operator 

Example 

Meaning 

+ 

A + B 

Adds B to A 

- 

A-B 

Subtracts B from A 

* 

A*B 

Multiplies A by B 

/ 

A/B 

Divides A by B 


A*B 

Calculates A to the B power 


The following examples show how BASIC-PLUS handles real and integer 
data in arithmetic expressions. An operation on two numeric operands of 
the same data type yields a result of that type. For example: 

A% -I- B% produces an integer value. 

A -I- B produces a real value. 

An integer and a real quantity produce a real value. For example: 

A * B% produces a real value. 

6.87 * 5% produces a real value. 

When you assign a value of one data type to a variable of a different data 
type, BASIC-PLUS converts the value to the variable’s data type. For 
example: 

A = 5% » 35X 

Even though 5% and 35% are integer values, this statement assigns the 
% real value 175.0 to the real variable A. 

In general, two arithmetic operators cannot occur consecutively in the same 
expression. The exceptions are the unary plus and unary minus, which 
specify that a number is positive or negative. For example: 

A * +B is valid 
A * -B is valid 
A * (—B) is valid 
A - * B is not valid 

Because BASIC—PLUS assumes unsigned numbers are positive, the unary 
plus is optional. You must use the unary minus to specify a negative 
number. 


Building Statements 8-8 










8.4.2 String Expressions 

String expressions are strings separated by the plus sign (+). The plus sign 
concatenates (combines) the strings. For example: 

10 C* = "The street nante" + " is Seashore Drive" 

20 PRINT C» 

30 END 
RUNNH 

The street name is Seashore Drive 

You can use string expressions to: 

• Create long strings 

• Combine string constants and string variables 

• Combine several string variables 

8.4.3 Reiationai Expressions 

A relational expression consists of two operands (constants, variables, fimc- 
tions, or expressions) separated by a relational operator. The relational 
operator causes BASIC-PLUS to compare the two operands and determine 
if the indicated relationship is true or false. 

There are two types of relational expressions, numeric and string. Numeric 
relational expressions compare numeric operands; string relational expres¬ 
sions compare string operands. 

You use relational expressions in conditional statements (such as 
IF—THEN statements and conditional FOR loops) and in statement modi¬ 
fiers to control the order of program execution. String relational expres¬ 
sions also let you sort string ^ta into alphabetical order. 

The following IF-THEN statement contains a relational expression that 
controls program execution: 

300 IF ANSMER$ = "YES" THEN GOTO 1000 > 

# 

When this statement is executed, BASIC-PLUS tests the current value 
of the string variable ANSWER$. If ANSWER$ contains the value YES, 
BASIC—PLUS evaluates the expression ANSWER$ = "YES” as "true” and 
control goes to line 1000 in the program. If ANSWER$ contains any other 
string value, BASIC—PLUS evaluates the expression ANSWER$ = "YES” 
as "false” and control goes to the next line number in the program. 

Relational expressions are evaluated as -1 if the relation is true and 0 if 
the relation is false. These numbers are logical values. You need not 
remember these values to use relational expressions; BASIC-PLUS uses 
them to meein "true” and "false” and continues executing your program 
accordingly. You do need to know these values, however, if you want to 
process them in a program. (Chapter 11 explains how to process logical 
values.) 
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The rest of this section describes relational expressions in detail and gives 
more examples of how to use them. 

8.4.3.1 Numeric Relational Expressions 

Numeric relational expressions consist of numeric operands separated by 
relational operators. When used with numeric operands, relational opera¬ 
tors compare the operands to determine if a numeric expression is true or 
false. 

Table 8-3 lists numeric relational operators. 


Table 8-3: Numeric Relational Operators 


BASIC-PLUS 

Symbol 

Example 

Meaning 

= 

A=B 

A is equal to B. 

< 

A<B 

A is less than B. 

< = 

A< = B 

A is less than or equal to B. 

> 

A>B 

A is greater than B. 

> = 

> 

V 

II 

w 

A is greater than or equal to B. 

<> 

AoB 

A is not equal to B. 


A==B 

A is approximately equal to B. 


The term "approximately equal to” means that the two quantities look the 
same when you print them with the PRINT statement. Numbers are stored 
internally at greater than 6 digits of precision but are rounded to 6 digits 
for output. Two numbers that are identical when rounded to 6 digits of 
precision are approximately equal (= =). These numbers may be close 
enough in value for some calculations. By contrast, two numbers equal to 
the internal limits of precision are truly equal (=). 

The next example compares two real numbers: 

10 INPUT "Enter a value for A"5A 
20 INPUT "Enter a ualue for B"!B 
30 IF A = B THEN PRINT “A is equal to B" 

40 IF A < B THEN PRINT "A is less than B" 

50 IF A > B THEN PRINT "A is Greater than B" 

32767 END 

When you run this program, it prompts you to enter values for the real 
variables A and B. It compares the two values and then prints one of three 
messages depending on the values you entered. For example: 

RUNNH 

Enter a ualue for A? 10*02® 

Enter a ualue for B? 10*021® 

A is less than B 

Ready 
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8.4.3.2 String Relational Expressions 

String relational expressions consist of string operands separated by rela¬ 
tional operators. The relational operators compare the value of the string 
operands, which can be strings or string expressions. Like numeric rela¬ 
tional expressions, string relational expressions are evaluated as true or 
false. 

BASIC—PLUS uses the ASCII character collating sequence to determine 
the relative character values (see Appendix D). It compares the strings 
character by character, from left to right, until it finds a difference in 
ASCII value. Because the ASCII collating sequence is an alphabetic 
sequence, you can use string relational expressions to sort string data into 
alphabetical order. 

Table 8-4 lists string relational operators and their meanings. 


Table 8-4: String Relational Operators 


Operator 

Example 

Meaning 

= 

PQ 

II 

< 

The strings A$ and B$ are equal, exept for possible trailing 
spaces. 

< 

A$ < B$ 

String A$ precedes string B$ in alphabetic sequence. 

< = 

A$ <= B$ 

String A$ is equal to or precedes string B$ in alphabetic 
sequence. 

> 

A$ > B$ 

String A$ follows string B$ in alphabetic sequence. 

> = 

A$ > = B$ 

String A$ is equal to or follows string B$ in alphabetic 
sequence. 

<> 

A$ <> B$ 

The strings A$ and B$ are not equal. 


PQ 

II 

II 

The strings A$ and B$ are identical, including trailing spaces. 
That is, the strings have both the same length and character 
composition. 


BASICJ-PLUS ignores trailing spaces in a string comparison, except when 
you use the = = operator. When you use other operators, ’'YES” is the 
same as "YES ”. 

Like numeric relational expressions, string relational expressions let you 
control the order in which statements are executed. For example: 

10 A* = "ABC" 

20 B$ = "DEF" 

30 IF A* < B* GOTO BO 
AO PRINT A$ 

50 PRINT B$ 

60 END 
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When you run this program, BASIC-PLUS compares the first character in 
each string to determine if A$ occurs first in ASCII collating sequence. 
Because '"A” precedes '"D” in the ASCII table, A$ precedes B$ in the collat¬ 
ing sequence. Program control shifts to line 60 and program execution ends. 
No values are printed. 

If you change the program so that A$ is the string "'DBF” and B$ is the 
string ''ABC, A$ no longer precedes B$ in the collating sequence. Program 
execution continues at line 40. The program prints the values of A$ and B$ 
before execution ends. For example: 


10 A$ = "DEF" 

20 = “ABC" 

30 IF A$ < B$ GOTO BO 
40 PRINT A$ 

50 PRINT B$ 

60 END 
RUNNH 
DEF 
ABC 


When BASIC-PLUS compares two strings of unequal length, it compares 
the shorter string (length n) with the first n characters of the longer string. 
When the first n characters of the strings are the same, the strings are 
equal if the rest of the characters in the longer string are blanks. Other¬ 
wise, the longer string is greater than the shorter string. The following 
example compares strings of equal and unequal lengths: 


100 INPUT “Enter a value for A$“5A$ 

200 INPUT “Enter a value for B$“fB$ 

300 IF A$ > B$ THEN & 

PRINT A$5 " COMES AFTER “ ; B$ & 
ELSE IF B$ > A$ THEN & 

PRINT A$5 ” COMES BEFORE “ 5 B$ & 

ELSE PRINT A$; “ IS THE SAME AS “; B$ 
32767 END 


When you run this program, it prompts you to enter values for the string 
variables A$ and B$. It compares the two values and then prints one of 
three messages depending on the values you entered. For example: 

RUNNH 

Enter a value for A$? ABC® 

Enter a value for B$? ABCDEF® 

ABC COMES BEFORE ABCDEF 

Ready 

RUNNH 

Enter a value for A$? ABCDEF® 

Enter a value for B$? ABC® 

ABCDEF COMES AFTER ABC 

Ready 
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RUNNH 

Enter a value for A$? APPLE ® 

Enter a value for B$? APPLE® 

APPLE IS THE SAHE AS APPLE 

Ready 


A null string has a length of zero and is therefore less than any string of 
length greater than zero. However, a null string is the same as a string of 
blanks. Consider the following immediate mode example (the symbol "" 
represents a null string): 

IF "" = " “ THEN PRINT "EQUAL" ELSE PRINT "NOT EQUAL" 

EQUAL 

8.4.4 Logical Expressions 

A logical expression contains either: 


• One operand and a logical operator 


• Two operands separated by a logical operator 


Here are some examples of logical expressions: 

(A < 0.) AND (B = 1. ) 

((A > B) OR (C > D») AND A/B <> C/D 
NOT A 

Logical expressions are valid wherever numeric expressions are valid. 

There are two t 3 rpes of logical expressions: those with relational expressions 
as operands and those with integers as operands. The two types of logical 
expressions have different uses in BASIC-PLUS programming. This sec¬ 
tion describes logical expressions with relational expressions as operands; 
see Chapter 11 for information on logical expressions with integers as 
operands. 

Logical expressions that have relational expressions as operands are like 
relational expressions. BASIC—PLUS tests the relationship between the 
two operands and evaluates the expression as true or false. The logical 
operator determines what type of test BASIC-PLUS performs (see Table 
8-5). Like relational expressions, this type of logical expression returns -1 
for true and 0 for false. 

You use this t 3 ^e of logical expression the same way you use relational 
expressions; that is, in IF-THEN statements, conditional FOR loops, and 
certain other statements to control the order in which program statements 
are executed. 
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Table 8-5 lists the logical operators. Assume that A and B are relational 
expressions. 


Table 8-5: Logical Operators 


Operator 

Example 

Meaning 

NOT 

NOT A 

The logical opposite of A. If A is true, NOT A is false. If A is 



false, NOT A is true. 



AND 

AANDB 

The logical product of A and B. A AND B is true only if A is 



true and B is true. 



OR 

A ORB 

The logical sum of A and B. A OR B is true if either A or B or 
both are true. A OR B is false only if both A and B are false. 

XOR 

AXORB 

The logical exclusive OR of A and B. A XOR B is true if either 
A or B (but not both) is true. Otherwise, A XOR B is false. 

EQV 

AEQVB 

The logical equivalence of A and B. A EQV B is true if A and B 
are both true or both false. Otherwise, A EQV B is false. 

IMP 

AIMPB 

The logical implication of A and B. A IMP B is false if A is true 
and B is false. Otherwise, A IMP B is true. 

The truth values in 

Table 8-6 summarize 

the results of these logical 

operations. 





Table 8-8: 

Truth Values for Logical Operations 


A B 

AANDB 

A B 

A ORB 


T T 

T 

T T 

T 


T F 

F 

T F 

T 


F T 

F 

F T 

T 


F F 

F 

F F 

F 


A B 

AXORB 

A B 

AEQVB 


T T 

F 

T T 

T 


T F 

T 

T F 

F 


F T 

T 

F T 

F 


F F 

F 

F F 

T 


A B 

AIMPB 

A 

NOT A 


T T 

T 

T 

F 


T F 

F 

F 

T 


F T 

T 




F F 

T 
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Note tile following: 

• The operators XOR and EQV are opposites. 

• BASIC—PLUS generally accepts any nonzero value as true. 

8.4.5 How Expressions Are Evaluated 

BASIC—PLUS evaluates expressions according to its rules of operator pre¬ 
cedence. Imagine a list of all the arithmetic, string, relational, and logical 
operators described in this chapter. Each operator has a fixed position or 
rank in this list. The operator’s position tells BASIC-PLUS when to per¬ 
form the operation. You can use parentheses to change the order of preced¬ 
ence. Table &-7 shows operator precedence. 

Table 8-7; Operator Precedence 


Exponentiation C or Highest 

Unary minus (~) 

Multiplication and division (♦,/) 

Addition and subtraction ( + ,-) 

String concatenation (+) 

All relational operators 

NOT 

AND 

OR, XOR 

IMP 

EQV Lowest 


BASIC—PLUS evaluates expressions according to the following rules: 

1. Expressions inside parentheses are evaluated first. When you place one 
set of parentheses inside another set (called nesting), the expressions 
are evaluated from the inside out. For example: 

B = 5 * < 2 * (3 + 2) ) 

This expression assigns the value 160 to B. Because (3 + 2) is the 
innermost parenthetical expression, BASIC-PLUS evaluates it first. 
Then it evaluates (2 '' 5) and finally (5 * 32). 

2. After expressions in parentheses are evaluated, BASIC-PLUS performs 
operations in the order they appear in Table 8-7. The expression 
from the previous example without parentheses shows the order of 
operations: 

B = 5*2*3 + 2 
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This expression assigns the value 42 to B. First BASIC-PLUS evalu¬ 
ates 2^3, then 5*8, and finally 40 + 2. 

3. When expressions contain operators of equal rank in the table, 
BASIC-PLUS performs operations from left to right. For example, 
BASIC-PLUS evaluates A"B"C as (A^BIX, A/B/C as (A/B)/C, and 
A*B/C aa (A*B)/C. 

You are encouraged to use parentheses even though they are not required. 
They make expressions easier to read and also help you write correct 
expressions. 
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Chapter 9 

Elementary Statements and Features 


This chapter describes the elementary BASIC-PLUS statements and 
features. Here is a guide to its contents: 


Topic 

Statements or Functions 

Assigning Values to Variables 

Introduction to Input/Output 

Unconditional Branching 

Conditional Branching 

Program Loops 

Subscripted Vfiriables 

Mathematical Functions 

LET 

PRINT, INPUT, READ, DATA, RESTORE 

GOTO 

IF-THEN, IF-GOTO 

FOR-NEXT, WHILE-NEXT, UNTIL-NEXT 

DIM 

ABS, SGN, INT, FIX, COS, SIN, TAN, ATN, SQR, EXP, 
LOG, LOGIC, PI, RND, RANDOMIZE 

User-Defined Functions 

DEF* 

Subroutines 

GOSUB, RETURN 

Ending or Halting Execution 

END, STOP 


The statements and features described in this chapter are sufficient, by 
themselves, for the solution of many programming problems. Once you 
master them, you can investigate their more advanced applications, as well 
as other statements and features described in Parts III and IV. The more 
advanced features can help you solve more complex problems and write 
more efficient programs. 
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9.1 LET Statement 


The LET statement assigns a value to a veiriable. LET has the form: 


[LET] <variable(B)> = <expre88ion> 


The LET statement does not indicate algebraic equality. Instead, it assigns 
the results of the expression to the indicated variable. For example: 

10 LET X = x+i 

20 LET M2 = (A4-X3>*<Z-A/B) 


In line 10, the old value of X is increased by 1 and becomes the new value 
of X. In line 20, the expression on the right-hand side is evaluated using the 
current values for A4, X3, Z, A, and B, and the result is assigned to W2. 

The LET statement can be a simple numerical assignment, such as: 

50 LET A = 35 


For example: 


50 LET A = 35 
60 PRINT A 
70 LET A = A+1 
80 PRINT A 
90 END 
RUNNH 

35 

36 


Ready 


The LET statement can also evaluate an expression that is continued on 
more than one line. For example: 

40 LET X = (H-X4*3)*(Z-A/ & 

(A-B)-17) 

For convenience, you can omit the word LET from the LET statement. 
Omitting LET does not change the effect of the statement. For example, 
you may find it easier to tjrpe the first statement than the second 
statement: 

10 X = 12»(S+7) 

10 LET X = 12»(S+7) 
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You can use the LET statement anywhere in a multiple statement line. For 
example: 

10 X = 44 \ Y =X*2+Yl \ B2 = 35*A 

The LET statement also lets you assign the same value to several variables 
in the same statement. For example: 

10 LET X. Y » 2 = 5.7 

Line 10 sets each of the three variables equal to 5.7. 

Do not use a LET statement of this form to assign the same value to several 
variables: 

20 LET X = Y = 5.7 

This statement assigns the value —1 to X if the expression (Y = 5.7) is true 
and the value 0 to X if the expression (Y = 5.7) is false. (See Section 8.4.3.) 

9.2 introduction to Programmed input and Output 

This section describes the basic techniques for performing BASIC-PLUS 
program input/output, usually abbreviated to I/O. The term I/O means 
bringing data from a file or device into a program for processing and send¬ 
ing it to a file or device after processing. The file may be stored on disk or 
magnetic tape; the device may be a terminal, a line printer, or other periph¬ 
eral device. 

You perform basic I/O operations in BASKD-PLUS with PRINT and 
INPUT statements. The basic forms of these statements are presented in 
this section to help you create simple BASIC-PLUS programs and get tan¬ 
gible results. This section also describes the READ, DATA, and RESTORE 
statements, which you use to supply a fixed list of values to your program. 
The values are contained in the program itself; they are not supplied from 
outside the program. 

Part IV of this manual describes more advanced I/O techniques. 

9.2.1 PRINT Statement 

The PRINT statement prints data to a device or file. In this introduction to 
the PRINT statement, your terminal is the output device. Chapter 15 con¬ 
tains a complete description of the PRINT statement. 

The format of the PRINT statement is: 

PRINT [list] 
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The list, which is optional, can contain expressions, character strings, 
numeric constants, and variables. A PRINT statement without any 
operands prints a blank line. 

PRINT statements evaluate expressions and print results. All expressions 
in a list are evaluated before BASIC-PLUS prints a value. Consider the 
following program; 

LISTNH 

2000 LET A=1 \ LET B=2 \ LET C=3+A 

2100 PRINT 

2200 PRINT A+B+C 

327G7 END 

Ready 

RUNNH 

7 

Ready 

You can use the PRINT statement anywhere in a multi-statement line. For 
example: 

10 A=1 \ PRINT A \ A=A+5 \ PRINT \ PRINT A 

This line prints: 

1 

6 

BASIC-PLUS prints a carriage return/line feed at the end of each PRINT 
statement by default. Thus, the first PRINT statement prints a "1” and a 
carriage return/line feed. The second PRINT statement prints the blank 
line, and the third PRINT statement prints a ”6” and another carriage 
return/line feed. 

9.2.1.1 Printing Numbers and Character Strings 

When printing positive numbers, BASIC—PLUS adds a leading and a trail¬ 
ing blank space. When printing negative numbers, BASIC—PLUS adds a 
leading minus sign and a trailing blank space. For example: 

PRINT 105-20530 
10 -20 30 

(The semicolon prints values in a "packed” format - see Section 9.2.1.2.) 
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The PRINT statement can also print characters. You delimit characters for 
printing by placing single or double quotation marks at each end of the 
string. The same type of quotation mark is necessary at the beginning and 
the end of each string. For example: 


LISTNH 

100 PRINT "TIME'S UP" 

no PRINT 'OUOTH THE RAVEN* "NEVERMORE"' 

32767 END 

Ready 

RUNNH 
TIME'S UP 

OUOTH THE RAVEN* "NEVERMORE" 


Ready 


When BASIC—PLUS prints a string, it does not add leading or trailing 
spaces. Only the characters between quotation marks appear. To add lead¬ 
ing and trailing spaces, tjqie them inside the quotation marks with the 
keyboard space bar. Spaces are output exactly as you t 3 q)e them inside the 
quotation marks. 

You can also use PRINT to print combinations of characters and numeric 
values. For example: 

550 X=83.4 

580 PRINT "AVERAGE GRADE IS"!X 


This example prints: 

AVERAGE GRADE IS 83.4 


9.2.1.2 Formatting the Output 

You specify how you want output formatted by using either commas or 
semicolons between items in the PRINT list. Use commas if you want 
values widely spaced across the terminal line; use semicolons if you want 
values printed without added spaces. 

Commas print items in print zones. BASIC-PLUS considers a terminal line 
to be divided into print zones of 14 spaces each. On terminals where the 
maximum print line contains 80 character positions, there are 5 print 
zones. Terminals with 84 or more characters per line have additional print 
zones of 14 spaces each. 
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When a comma follows an item in a PRINT statement, the next value to be 
printed appears in the next available print zone. For example: 

LISTNH 

10 LET A=3* \ LET B=2. 

20 PRINT A>A+BfA-B#B-A 

Ready 

RUNNH 

3 2 5 6 1 

-1 9 


BASIC-PLUS prints the sixth element in the PRINT list as the first entry 
on a new line because an 80—character line has five print zones. 

Two commas together in a PRINT statement cause a print zone to be 
skipped. For example: 

LISTNH 

100 REM ILLUSTRATES PRINT ZONES AND LINE CONTINUATIONS. 


110 

LET A=1 8c 
\ LET B = 2 8c 
\ PRINT A fB # fA+B 8c 

0 


INOTE DOUBLED COMMA 

AFTER B 

32767 

Ready 

END 


RUNNH 

1 

Ready 

2 

3 


Use the semicolon between PRINT list items instead of the comma if you 
want a tighter packing of printed values. A semicolon prints no extra 
spaces. The following examples compare the effects of the semicolon and 


comma. 



LISTNH 

100 

LET A 

= 1 8c 


\ LET 

B = 2 8c 


\ LET 

C = 3 

110 

PRINT 

a;b;c; 

120 

PRINT 

A+i; B+i; c+1 

130 

PRINT 

A >B » 

lAO 

PRINT 

A+B+C fC'^B fCMB^C) 

150 

PRINT 


160 

PRINT 

50 #10051505200 #250 #300 

32767 

END 


Ready 



RUNNH 




1 2 3 2 3 4 

12 3 6 

6561 

50 100 150 200 250 

Ready 


9 

300 
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LISTNH 

150 LET X-257Q, 

160 LET G>89. 

170 LET A*90.6 

190 LET R=ia 


!STUDENT NUHBER 
I GRADE 
!AVERAGE 
{RANK 


300 N=582 

940 PRINT 'STUDENT NUMBER'; X* 'GRADE ='iG; 

650 PRINT 'AVERAGE ='; A 

6S0 PRINT ' RANK IN CLASS'; R; 'OF'; N 

32767 END 

Ready 

RUNNH 

STUDENT NUMBER 2574 GRADE = 89 AVERAGE = 90.6 

RANK IN CLASS 14 OF 562 


Ready 


You can omit the semicolon between a text string and another item. How¬ 
ever, its use is recommended for compatibility with BASIC-PLUS-2. 

As noted, BASIC—PLUS automatically prints a carriage return/line feed 
at the end of each PRINT statement. To suppress the automatic carriage 
return/line feed, end the PRINT list with a comma or a semicolon. If you 
use a comma, the next PRINT statement starts printing in the next avail¬ 
able print zone. For example: 

LISTNH 

no LET A = 1 8. 

\ B = 2 8, 

\ C = 3 

130 PRINT A# 

lao PRINT B 

150 PRINT C 

32767 END 

Read/ 

RUNNH 

1 2 
3 

Ready 


If you use a semicolon, the next PRINT statement starts printing in the 
next space on the terminal line. 

9.2.2 INPUT Statement 

The INPUT statement provides data to a program while it is r unning The 
data comes from a device or a file. In this section, which introduces the 
INPUT statement, your terminal is the input device. Chapter 15 of this 
manual contains a complete description of the INPUT statement. 
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The INPUT statement has the form; 

INPUT <variable list> 

The list can contain real, integer, and string variables. When an INPUT 
statement is executed, the program halts, and BASIC-PLUS prints a ques¬ 
tion mark on the terminal and waits for you to supply data. 

For example, suppose you enter this INPUT statement into a program: 

50 INPUT A>6»C 

During program execution, this statement causes BASIC-PLUS to print a 
question mark on the terminal and wait for you to enter three numeric 
values. For example: 

RUNNH 

7 

In response to the question mark, t 5 q)e three numeric values separated by 
commas. After entering the values, press the RETURN key to pass the 
values to your program. 

If you type too few values on a line, BASIC—PLUS prints another question 
mark to indicate that it needs more data. If you type too many values on a 
line, BASIC—PLUS ignores any extra ones. Enter no more than 132 charac¬ 
ters, including commas between values, before you press the RETURN key. 
The INPUT statement allows you to enter more than 132 characters on a 
line but may not always read long input lines correctly. 

The example just shown points out a problem with the prompting question 
mark; it lets you know that input is expected, but it does not tell you what 
kind of input to enter or how many values to type. To avoid this problem, 
you can add a PRINT statement to print a prompting message at execution 
time. For example; 

40 PRINT “Enter 3 numbers separated by commas and press RETURN*" 
50 INPUT A>6»C 

RUNNH 

Enter 3 numbers separated by commas and press RETURN* 

7 

You can also include a prompting message in the INPUT statement itself. 
Use single or double quotation marks to set the message off from other 
parts of the statement. For example, the following statements have the 
same result: 

110 INPUT "YOUR AGE IS";A 
110 INPUT 'YOUR AGE IS'5A 
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Either statement has the same result as: 

110 PRINT "YOUR AGE IS"; 

120 INPUT A 

When you include a prompting message in an INPUT statement, you can 
use either a comma or a semicolon to separate the string you want printed 
from the input variable names. These formatting characters work the same 
way they do in the PRINT statement. 

The following program computes the academic standing of a student. Four 
INPUT statements prompt for the necessary data. Each INPUT statement 
prints a prompt to indicate what kind of data to enter. The program uses 
PRINT statements to print the results. The PRINT statements also print 
text to describe the results. The output for the program begins after the 
command RUNNH. 


LISTNH 

150 

160 

170 

180 


INPUT 'STUDENT NUMBER'?X 
INPUT 'GRADE'fG 
INPUT 'AVERAGE'iA 
INPUT 'RANK';R 


300 N = 562 

640 PRINT 'STUDENT NUMBER'; X# 'GRADE =';g; 

650 PRINT 'AVERAGE ='; A 

660 PRINT ' RANK IN CLASS'; R; 'OF'; N 

32767 END 

Ready 

RUNNH 

STUDENT NUMBER? 2574 
GRADE? 89 
AVERAGE? 90*6 
RANK? 14 

STUDENT NUMBER 2574 GRADE = 89 AVERAGE = 90.6 

RANK IN CLASS 14 OF 5B2 


Ready 


9.2.3 READ and DATA Statements 

Like the INPUT statement, the READ and DATA statements supply data 
to a program. However, unlike INPUT, the data is contained in the pro¬ 
gram itself instead of coming from a source outside the program (such as 
your terminal). 

READ and DATA differ from INPUT in another way. When you use 
INPUT to supply data, it can differ each time the program is run. On the 
other hand, READ and DATA supply a fixed list of data values to your 
program. You must edit the program to change the values. 
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A READ statement inputs the list of variables whose values it gets from a 
DATA statement. Neither statement works without the other, and the two 
statements must have compatible sequences. 

A READ statement has the form: 

READ <variable liBt> 

A DATA statement has the form: 

DATA <value li8t> 

With a READ statement, the variables you list sire assigned values sequen¬ 
tially from the set of DATA statements in the program. Before you run the 
program, BASIC-PLUS takes all DATA statements in the order they 
appear and creates a data block. Each time a READ statement is encoim- 
tered, BASIC-PLUS supplies the next value from the data block. If 
the data block runs out of data and another READ statement is executed, 
BASIC-PLUS prints the message: 

?Out of data at line n 

READ and DATA statements appear as follows: 

150 READ X» YZ. Zt SI* Y2 * 09 
330 DATA A* 2* 1.7 

3a0 DATA 6.73E-3. -174.321. 3.1415927 


Line 150 makes the assignments: 

X = 4.0 
Y% = 2% 

Z = 1.7 
SI = 6.73E-3 
Y2 = -174.321 
Q9 = 3.1415927 

Do not include the percent (%) character when you specify integer values in 
a DATA statement. If you do, you get the following error when you run the 
program: 

ZData format error at line n 


The next example contains real, integer, and string data: 

10 READ A* A$* AZ« 5$ 

50 DATA 12.5* NOW* 12* "QUOTED STRING" 

This example eissigns 12.5 to the real variable A, NOW to the string varia¬ 
ble A$, 12 to the integer variable A%, and QUOTED STRING to the string 
variable B$. 


9-10 


Elementary Statements and Features 





You can read a numeric value without a decimal point into an integer 
variable or a real variable. For example: 

10 READ A 10 READ AZ 

50 DATA 12 50 DATA 12 

In the first example, 12 is stored as a floating-point number. In the second 
example, 12 is stored as an integer. However, you cannot read a floating¬ 
point number into an integer variable: 

10 READ AZ 
20 DATA 1.1 
RUNNH 

XData format error at line 10 

If you read a number into a string variable, the number is stored as a string 
of ASCII characters. For example: 

30 READ A$ 

40 DATA 100 

These statements read the character string ”100” into A$. 

When you specify strings in DATA statements, include quotation marks 
around strings that contain: 

• One or more commas 

• Significant spaces or tabs 

• Lowercase letters that should not be converted to uppercase 

If you do not include quotation marks, BASIC—PLUS ignores spaces £md 
tabs in the string and converts lowercase letters to uppercase. 

The optional MAT READ statement allows you to read matrices from 
DATA statements. See Chapter 12 for more information. 

You must read in data before you can use it in a program. Thus, you 
normally place READ statements near the begiiming of a program. You 
can place DATA statements anywhere in a program; however, it is good 
programming practice to place DATA statements together near the end of 
the progreun. DATA statements eire read in order of their line numbers, so 
they must appear in the correct sequence. 

You can place a READ statement anywhere in a multi-statement line. But 
a DATA statement must be the only statement in a line or the last state¬ 
ment in a multi-statement line. 

You cannot place a comment at the end of a DATA statement. If you 
include a comment and the last item in the DATA statement is a string, 
BASIC—PLUS converts the comment to uppercase, removes spaces and 
tabs, and includes it in the string. If you include a comment and the last 
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item in the DATA statement is an integer or floating-point number, 
BASIC-PLUS returns the "%Data format error” when you run the 
program. 


9.2.4 RESTORE Statement 

You may need to use the same data more than once in a program. The 
RESTORE statement lets you recycle through the complete set of DATA 
statements in the program, beginning with the lowest numbered DATA 
statement. 

The RESTORE statement has the form: 

RESTORE 


RESTORE causes the next READ statement to begin reading data from the 
first DATA statement in the program. It does so regardless of where it read 
the last data value. 

You can use the same variable names the second time through the data, 
since the values are being read as though for the first time. Place dummy 
variables in the READ statement to skip imwanted values. (A "dumm^’ 
variable is a variable you make no further use of in the program.) Consider 
the following example of the RESTORE statement: 

LISTNH 

100 REM THIS PROGRAM ILLUSTRATES USE OF THE RESTORE STATEMENT 
1500 READ N \ PRINT 'VALUES OF X ARE:' 

IBOO FOR I = 1 TO N \ READ X \ PRINT X» 

1700 NEXT I 
1800 RESTORE 

1900 PRINT \ PRINT 'SECOND LIST OF X VALUES' 

2000 PRINT 'FOLLOMING RESTORE STATEMENT:' 

2100 FOR 1=1 TO N \ READ X \ PRINT X» 

2200 NEXT I 
6000 DATA 4 >1<2 
6100 DATA 3>4 
32767 END 

Ready 

RUNNH 

VALUES OF X ARE: 

12 3 4 

SECOND LIST OF X VALUES 

FOLLOMING RESTORE STATEMENT: 

4 12 3 

Ready 


Note that BASIC-PLUS prints the following on the last line: 

4 12 3 


These numbers are printed because BASIC-PLUS did not skip the value for 
the original N when it executed the loop beginning at line 2100. 


9-12 Elementary Statements and Features 





9.3 Unconditional Branch, GOTO Statement 

The GOTO statement transfers program execution immediately uncon¬ 
ditionally to a specified program line number. (Usually the specified line is 
not the next sequential line in the program.) The statement has the form: 
GOTO <line number> 

The line number to which program execution branches can be greater than^ 
less than, or the same as the current line number. 

Consider the following example: 

LISTNH 

10 LET A=2 

20 GO TO 50 

30 LET A=SQR (A+14) 

50 PRINT AtA*A 

32767 END 

Ready 

RUNNH 

2 a 

Ready 

When the program reaches line 20, control transfers to line 50. After line 
50 is executed, the program ends. Line 30 is never executed. Any number of 
lines can be skipped in either direction. 

Because any statement after GOTO on the same line is never executed, 
(tOTO should always be the last statement on a multi-statement line. For 
example: 


110 

LET A=517* & 

1 10 

LET A=517* 

& 


\PRINT A & 


\G0 TO 370 

& 


\G0 TO 370 


\PRINT A 


370 

PRINT 'FINISHED' 

370 

PRINT 'FINISHED' 

32767 

END 

32767 

END 


RUNNH 


RUNNH 



517 


FINISHED 


FINISHED 






Ready 




Ready 


9.4 Conditional Branch, IF—THEN and IF—GOTO Statements 


The IF—THEN and IF—CJOTO statements conditionally transfer program 
execution to a specified line number or statement, depending on the out¬ 
come of some test or relationship. The format of the IF statement is: 


IF <condition> 


THEN <statement> 
THEN <line number> 
GOTO <line number> 
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When the IF statement is executed, the specified condition is tested. If the 
condition is false, control goes to the next sequentially numbered line after 
the IF statement. If the condition is true, the statement after THEN is 
executed or control is transferred to the line number given after THEN 
or GOTO. (Section 13.5 describes an extension of this statement, the 
IF-THEN-ELSE statement.) 

The deciding condition can be either: 

• A simple relational expression where two numeric or string expressions 
are separated by a relational operator 

• A logical expression where two relational or logical expressions are sepa¬ 
rated by a logical operator 

For example: 

Relational Expression Logical Expression 

A+2>B (A>B) and (B <= SOR(C)) 

When either type of expression is evaluated, the result is either true or 
false. Sections 8.4.3 and 8.4.4 describe the relational and logical operators. 
They also appear in Appendix A. 

The following line contains a relational expression: 

75 IF A*B> = B*(B+n THEN LET Da = Da+l 

This line compares the quantities A*B and B*(B -f 1). If the first value is 
greater than or equal to the second value, the program increments the 
variable D4 by 1. The program does not increment D4 if B*(B -I- 1) is greater 
than A*B; instead, control passes immediately to the line following line 75. 

When a line number follows the word THEN, the IF-THEN statement is 
the same as the IF—GOTO statement. Any executable BASIC—PLUS state¬ 
ment can follow the word THEN, including another IF statement. For 
example: 

250 IF A>B THEN IF B>C THEN PRINT ••A>B>C" 

250 IF A>B AND B>C THEN PRINT •'A>B>C" 

The preceding two lines are logically equivalent. If B is less than A and 
greater than C, BASIC-PLUS prints: 

A>B>C 

Otherwise, the next line is executed. 

In the following example, the IF—GOTO statement in line 110 limits the 
value of the variable A in line 100. It uses a program loop to do so (see 
Section 9.5). A program loop is a series of statements written so that, when 
the statements are executed, control transfers to the beginning of the state¬ 
ments. This process continues until some terminating condition is reached. 
Execution of the loop continues imtil the relationship A>4 is true, and then 
line 32767 is executed to end the program. 


9^14 Elementery Statements and Features 




LISTNH 

100 LET A=A+1 & 

\ X»A*2 

110 IF A>4 GO TO 32767 

120 PRINT 'X='X» '♦ AND VALUE OF A IS' 

130 GO TO 100 

327B7 END 

Ready 

RUNNH 

X» 1 » AND VALUE OF A IS 1 

X= a , AND VALUE OF A IS 2 

X= 9 » AND VALUE OF A IS 3 

X= 16 » AND VALUE OF A IS 4 

Ready 


A 


The next example uses IF-THEN statements: 


100 IF A>B THEN 340 

200 IF (A*B> OR (B=C) THEN 260 

300 IF A>B THEN A=-B \ CONDITIONAL ASSIGNMENT 

400 IF <X>Y) IMP (Y>Z) THEN PRINT ”QED" 


To avoid confusion, you usually make an IF statement the last statement 
on a multi-statement line. 

When an IF statement is not the last statement on a multi-statement line, 
all statements on a program line after the THEN keyword are executed 
only if the related expression is true. 

For example: 


LISTNH 

90 INPUT 'ENTER A VALUE'lA 

100 IF A=1 THEN PRINT Ai & 

\ PRINT "TRUE CASE" i, 

\ GOTO 32767 
110 PRINT “NOT = 1" 

32767 END 

Ready 

RUNNH 

ENTER A VALUE? 2 
NOT = 1 

Ready 

RUNNH 

ENTER A VALUE? 1 
1 TRUE CASE 

Ready 


9.5 Program Loops 

Computers perform repetitive tasks with speed and accuracy. For example, 
a computer can compute the square roots of all integers between 1 and 100 
in a very short amount of time. 
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Because computers are so well suited to repetitive tasks, programs are 
often written to repeat sequences of instructions. 

An efficient way to repeat a series of instructions is to write a program loop. 
When a loop is executed, the series of statements in the loop is repeated 
until a terminating condition is met. While you can write your own pro¬ 
gram loops, the BASIC-PLUS language provides statements that are 
designed for building program loops. These statements are FOR, WHILE, 
UNTIL, and NEXT. TTtie rest of tWs section shows you the advantages of 
program loops, describes their characteristics, and explains how to write 
them. 

The best way to see the advantage of loops is by example. The following 
three program segments all perform the same function. Each prints a table 
of the square roots of the positive integers 1 through 100, together with 
their square roots. The first program segment does not use a loop, 
the second contains a user-written loop, and the third uses a built-in 
BASIC-PLUS feature called a FORr-NEXT loop. 

Without a loop, the first program segment is 101 lines long and reads: 

10 PRINT 1 > S0R<1) 

20 PRINT 2* SOR(2) 

30 PRINT 3* S0R<3> 


990 PRINT 99» S0R<99) 
1000 PRINT 100* SOR(IOO) 
32767 END 


The second example uses a user-written loop to obtain the same table: 


10 LET X = 1 
20 PRINT X»S0R(X) 

30 LET X = X+l 

aO IF X <=100 THEN 20 

50 END 


Statement 10 assigns a value of 1 to X, initializing the loop. In line 20, both 
the value of X and its square root are printed. In line 30, X is incremented 
by 1. Line 40 checks whether X is still less than or equal to 100; if so, the 
next value of X and its square root are printed. 


You can also print the square root table with a FOR—NEXT loop: 


10 FOR X = 1 TO 100 
20 PRINT X* SOR(X) 
30 NEXT X 
aO END 
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Lines 10 through 30 of this program segment contain the FORn-NEXT loop. 
The FOR and NEXT statements in lines 10 and 30 cause the PRINT state¬ 
ment in line 20 to execute 100 times. After the number 100 and its square 
root are printed, X becomes 101. The condition in line 30 is now false, so 
control does not return to line 10. Control goes to line 40, which ends the 
program. 

All program loops have four characteristic parts: 

1. Initialization, the conditions that must exist for the first execution of 
the loop. 

2. The body of the loop, where the operation to be repeated is performed. 

3. Modification, which alters some value and makes each execution of the 
loop different from the one before and the one after. 

4. Termination condition, an exit test that, when satisfied, completes the 
loop. Execution continues to the program statements after the loop. 

BASIC—PLUS has two t5q)es of loops: 

1. FOR^NEXT loops, which use a counter to determine how many times to 
repeat a series of instructions. 

2. UNTIL—NEXT and WHILE—NEXT loops, which use a conditional 
statement to determine how many times to repeat a series of 
instructions. 

As their names indicate, a FORr-NEXT loop contains a FOR statement, an 
UNTIL-NEXT loop contains an UNTIL statement, and a WHILE-NEXT 
loop contains a WHILE statement. All three loops contain a NEXT 
statement. 

9.5.1 FOR and NEXT Statements 

The FOR and NEXT statements together define a FORr-NEXT loop. The 
FOR statement begins the loop; the NEXT statement ends the loop. You 
code the body of the loop between them. 

FORr-NEXT loops are controlled by a counter whose value is modified 
each time the body of the loop executes. This counter is called the control 
variable or loop index. You can let the control variable act only as a counter 
(and not reference it in body of the loop) or you can use the control variable 
inside the loop for processing. 

The FOR statement has the form: 

FOR <variable> = <expre8sion> TO <expression> [STEP <expression> ] 
where: 

<variable> is a numeric variable without a subscript 
<expression> is a muneric expression 
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The variable in the FOR statement is the loop’s control variable. While the 
control variable must be unsubscripted, it is common in the body of a loop 
to deal with subscripted variables, using the control variable as the sub¬ 
script of a previously defined variable. (See Section 9.6 for information on 
subscripted variables.) For the greatest efficiency, use integer variables for 
control variables in the range -32767 to 32766. Use real variables for 
larger values or fractional values. 

The expressions in the FOR statement must be numeric expressions as 
defined in Section 8.4. The first expression is the starting value for the 
control variable; the second is its final or terminal value. The optional 
STEP expression specifies the amount by which the control variable 
changes each time the loop is executed. 

A positive STEP value increments the control variable; a negative STEP 
value decrements the control variable. If you omit the STEP expression, 
BASIC—PLUS assumes a value of -i-l. (Because -i-l is a common STEP 
value, that portion of the statement is often omitted.) 

An example of the FOR statement is: 

10 FOR K* = 22 TO 202 STEP 22 

This statement cycles program execution through a loop using values 
for K% of 2, 4, 6, 8, and so on until 20. After the loop is executed with 
K% = 20%, the program exits from the loop. Control then passes to the line 
after the associated NEXT statement. 

The NEXT statement signals the end of a loop that begins with a FOR 
statement. The NEXT statement has the form: 

NEXT <variable> 

The variable in a NEXT statement is the same one as in the FOR state¬ 
ment. Together the FOR and NEXT statements describe the boundaries of 
the program loop. 

Upon encountering the NEXT statement, BASIC—PLUS adds the STEP 
value to the variable. Then it checks to see if the variable is still less than 
or equal to the terminal value. When the variable exceeds the terminal 
value, control falls through the loop to the statement following the NEXT 
statement. 

The expressions within the FOR statement are evaluated before the initial 
entry into the loop. The test for completion of the loop is made before the 
loop is executed and at the end of each iteration of the loop. If the first test 
inchcates completion, the loop is never executed. 

Although you can modify the control variable within the loop, this practice 
is not recommended. When control falls through the loop, the control varia¬ 
ble retains the last value used inside the loop. However, the terminal and 
STEP values are calculated only upon entry to the loop and do not change 
for the duration of the loop. 
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Consider the following program: 

LISTNH 
100 A=2*5 

no FOR 1-1 . TO 2. ♦A 
120 PRINT I#A 

130 A=n 
140 NEXT I 

Ready 

RUNNH 

1 2*5 

2 1 

3 1 

4 1 

5 1 


The loop stops when I equals 5, even though the value of A changed within 
the loop. 

The following examples show two loops that perform the same function. 
The loops are executed 10 times; the value of I is 10 when control leaves the 
loop (+1 is the assumed STEP value): 


LISTNH 

10 FOR 1=1 TO 10 
20 PRINT I ; 

30 NEXT I 
40 PRINT I 


LISTNH 
10 1 = 1 
20 PRINT I; 

30 IF I<10 THEN & 
1 = 1+1 & 

\ GO TO 20 
40 PRINT I 


Both program segments produce the same result when run: 

RUNNH 

123456789 10 10 


The numbers 1 through 10 are printed when the loop is executed. When I 
equals 10, control passes to line 40. Therefore 10, which is the current 
value of I, is printed again. Suppose line 10 had been: 

10 FOR I = 10 TO 1 STEP -1 

The value printed by line 40 would be 1. Note that a minus sign is neces¬ 
sary for decrementing a loop. 

The following loop is executed only once, since the value of I = 44 is reached 
in the first iteration and the termination condition is satisfied. 

10 FOR I = 2 TO 44 STEP 2 
20 LET I = 44 
30 NEXT I 
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If, however, the initial value of the variable is greater than the terminal 
value, the loop is never executed unless a negative STEP value is specified. 
A statement of the following format cannot be used to begin a loop: 

10 FOR I = 20 TO 2 STEP 2 

The statement that will execute the loop properly is: 

10 FOR I = 20 TO 2 STEP -2 

For positive STEP values, the loop is executed until the control variable is 
incremented past its final value. For negative STEP values, the loop contin¬ 
ues imtil decrementing the control variable causes the variable to be less 
than its final value. 


FOR loops can be nested but not overlapped. Nesting is a programming 
technique where one or more loops are contained inside another loop. The 
range of one loop (the numbered lines from the FOR statement through the 
corresponding NEXT statement) must not cross the range of another loop. 


The depth of nesting you can use depends on the size of the your program 
and the amount of memory that you have available. Figure 9-1 shows 
correct and incorrect nesting of loops. 


Figure 9-1: Nesting Techmques 


Correct 

Two-Level Nesting 


— FOR II = 1 TO 10 

C FOR 12 = 1 TO 10 
NEXT 12 

C FOR 13 = 1 TO 10 
NEXT 13 
— NEXT II 


Three-Level Nesting 


-FOR II = 1 TO 10 

-FOR 12 = 1 TO 10 

C FOR 13 = 1 TO 10 
NEXT 13 

C FOR 14 = 1 TO 10 
NEXT 14 

_NEXT 12 

_NEXT II 


Incorrect 


FOR II = 1 TO 10 
FOR 12 = 1 TO 10 
NEXT II 
NEXT 12 


-FOR II = 1 TO 10 

-FOR 12 = 1 TO 10 

C FOR 13 = 1 TO 10 
NEXT 13 

pFOR 14 = 1 TO 10 
UnEXT 14 

_NEXT II 

_NEXT 12 
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An example of nested FOR-NEXT loops follows: 


LISTNH 




100 

FOR AX=1X 

TO 

5X 

110 

FOR BX=2X 

TO 

lOX STEP 

120 

PRINT AX; 

BX # 


130 

NEXT BX 



140 

PRINT 



150 

NEXT AX 



32767 

END 



Ready 




RUNNH 




1 2 

1 

4 


2 2 

2 

4 


3 2 

3 

4 


4 2 

4 

4 


5 2 

5 

4 



B 18 1 10 

6 2 8 2 10 

B 3 8 3 10 

B 48 4 10 

6 5 8 5 10 


You can exit from a FOR-NEXT loop without the control variable reaching 
the termination value by executing a GOTO, GOSUB, or computed GOTO. 
When you transfer control into a loop, you should only enter a loop left 
incomplete earlier. This transfer ensures that termination and STEP 
values are assigned. It is not good programming practice to enter loops 
anywhere but at the beginning of the loop. 

Both FOR and NEXT statements can appear anywhere in a multi¬ 
statement line. For example: 


LISTNH 

100 FOR 1=1 TO 10 STEP 5\ NEXT I \PRINT 'I=';i 

Ready 

RUNNH 
1 = 6 

Ready 


Neither the FOR nor NEXT statement is executed conditionally in an IF 
statement. The following statements are incorrect: 

15 IF lOJ THEN NEXT I 
15 IF I=J THEN FOR 1=1 TO J 

Both statements generate the error message: 

?Illeeal IF statement at line 15 
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NOTE 


When the body of a loop contains only one statement, you can 
use FOR as a statement modifier to create a loop that is more 
efficient than a FOR-NEXT loop. See Section 13.6.3 for infor¬ 
mation about the FOR statement modifier. 

9.5.2 WHILE and NEXT Statements 

You can use the WHILE and NEXT statements to perform a loop while a 
specific condition continues to be true. A WHILE—NEXT loop is similar to a 
FORr-NEXT loop. 

The WHILE statement has the form: 

WHILE <condition> 

where <condition> is a relational or logical expression. 

The NEXT statement has the form: 

NEXT 

Do not include a variable in the NEXT statement. 

The following is an example of a WHILE-NEXT loop. The sample program 
runs until you respond: 

LISTNH 
10 A$ = 

20 WHILE LEN(A$) = OX 
30 INPUT "Enter name"? A* 

40 A$ = CVT$$(A*iZSSX) 

50 NEXT 
32767 END 

Ready 

RUNNH 

Enter name? ® 

Enter name? ® 

Enter name? ® 

Enter name? JOE® 

Ready 

Unlike a FOR-NEXT loop, a WHILEl-NEXT loop does not have a control 
variable that is automatically incremented. However, a WHILE-NEXT 
loop works much like a FORr-NEXT loop. For example, the iniles for termi¬ 
nation are similar. Before the loop is executed, BASIC-PLUS tests to see if 
a condition is true. If it is, a pass through the loop is made. If the condition 
is false, the loop is not executed. Compare the following: 

FOR I = 1 TO 5 
NEXT I 

WHILE I < 5 
NEXT 
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The FOR and NEXT statements execute the loop five times; the WHILE 
and NEXT statements execute the loop until the value of I is no longer less 
than five. 

Both FOR^NEXT and WHILE-NEXT loops follow the same rules for 
nesting. 

NOTE 

When the body of a loop contains only one statement, you can 
use WHILE as a statement modifier to create a loop that is 
more efficient than a WHILE—NEXT loop. See Section 13.6.4 
for information about the WHILE statement modifier. 

9.5.3 UNTIL and NEXT Statements 

You can use the UNTIL and NEXT statements to perform a loop until a 
condition is true. An UNTIL-NEXT loop is similar to a FOR-NEXT loop 
and a WHILE-NEXT loop. 

The UNTIL statement has the form: 

UNTIL <condition> 

where <condition> is a relational or logical expression. 

The NEXT statement has the form: 

NEXT 

Do not include a variable in the NEXT statement. 

The following example uses an UNTIL-NEXT loop. Like the example in 
the previous section, the sample program runs until you respond: 

LISTNH 
10 A$ = 

20 UNTIL LEN(A$) > OX 
30 INPUT "Enter nawe" ; A$ 
aO A$ = CUT$$(A$ #25571) 

50 NEXT 
327B7 END 

Ready 

RUNNH 

Enter name? ® 

Enter name? ® 

Enter name? (gED 
Enter name? JIM® 

Ready 


Like a WHILE-NEXT loop, an UNTIL-NEXT loop does not have a control 
variable that is automatically incremented. However, an UNTIL-NEXT 
loop works much like a FOR-NEXT loop. For example, the rules for termi¬ 
nation are similar. Before the loop is executed, BASIC-PLUS tests to see if 
a condition is false. If it is, a pass through the loop is made. If the condition 
is true, the loop is not executed. 
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UNTIL-NEXT loops follow the same rules for nesting as FOR-NEXT and 
WHILE-NEXT loops. 


NOTE 

When the body of a loop contains only one statement, you can 
use UNTIL as a statement modifier to create a loop that 
is more efficient than an UNTIL-NEXT loop. See Section 
13.6.5 for information about the UNTIL statement modifier. 

9.6 Subscripted Variables and the DIM Statement 

In addition to the simple variables described in Chapter 8, you can also use 
subscripted variables in BASIC—PLUS. A subscripted variable lets you 
break up a variable’s storage area into several compartments. You can then 
refer to each compartment as a unique storage location. A set of compart¬ 
ments defined by a subscripted variable is called a matrix or, more com¬ 
monly, an array. 

You can use subscripted variables for additional computing capa¬ 
bilities with lists, tables, matrices, or any set of related variables. In 
BASIC—PLUS, subscripted variables can have one or two subscripts. 
BASIC-PLUS has default sizes for one- and two-dimensional arrays. How¬ 
ever, you can specify the size of an array with the DIM statement. 

The name of a subscripted variable is any acceptable BASIC-PLUS varia¬ 
ble name, followed by one or two integer expressions in parentheses. If you 
use a floating-point number instead of an integer, the fractional portion is 
truncated. In other words, A(2.8) becomes A(2). 

The following example lists A(I), where I goes from 0 to 5. (All arrays are 
created with a zero element, even if that element is never specified.) 

A(0)« A<1)> A(2)> A(3>< A(a)» A<5) 

You can access each of six elements in the list, which can be shown as a 
one-dimensional array: 



You can define two-dimensional array B(I,J) in a similar manner, as in 
Figure 9-2. 

Subscripts used in subscripted variables can be constants or numeric 
expressions. You can use the same variable name as both a subscripted and 
an imsubscripted variable. Both A and A(I) are valid variables that can be 
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used in the same program without affecting one another. However, you 
cannot use the same variable name as both a singly and a doubly sub¬ 
scripted variable in the same program. 

Figfure 9-2: Array Structure 



Consider the following example: 


LISTNH 
100 A=7 
200 A(6) = U 
300 PRINT A 
400 PRINT A<B) 


Ready 

RUNNH 

7 

14 

Ready 


The preceding program segment is legal. If, however, you try to assign one 
variable name as both singly and doubly subscripted, the program does not 
run correctly: 

100 A(8)=>14 
200 A(B»2)=7 

Lines 100 and 200 generate the error message: 

ZInconsiStent subscript use at line 200 


NOTE 

There are cases where a variable name without subscripts 
refers to an entire array and not to a simple numeric varia¬ 
ble. See the CHANGE statement, described in Section 10.2, 
and the MAT statements, described in Chapter 12. 
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The dimension (DIM) statement defines the maximum number of elements 
in an array. The DIM statement has the form: 

DIM <variable(dimen8ion(8))> [,<variable(dimension(8))> ,...] 

The variables in a DIM statement are indicated with their maximum sub¬ 
script value(s). For example: 

10 DIM X(5) » Y(a»2)» A(10>10) 

12 DIM la(lOO) 

You can use only nonnegative integer constants in DIM statements to de¬ 
fine the size of an array. Any number of arrays can be defined in a single 
DIM statement as long as the variables defining them are separated by 
commas. 

If you use a subscripted variable without using a DIM statement, 
BASIC-PLUS assumes the variable’s highest element to be 10 in each 
dimension. The variable has elements 0 through 10 for a total of 11. How¬ 
ever, you should correctly dimension all arrays in a program. 

The first element of every array is automatically assumed to have a 
subscript of 0. Dimensioning A(6,10) sets up room for an array with 77 
elements, arranged in 7 rows and 11 columns. The following program illus¬ 
trates the 0 element: 

LISTNH 


10 

REM 

- MATRIX 

CHECK 

PROGRAM 

20 

DIM 

A(6 

#10) 






30 

FOR 

1=0 

TO 

6 





40 

LET 

Ad 

»0) = 

I 





50 

FOR 

J = 0 

TO 

10 





60 

LET 

A(0 

#J) = 

J 





70 

PRINT Ad »J) ; 






\ 

NEXT 

J 







\ 

PRINT 








\ 

NEXT 

I 






32767 

END 








Ready 










RUNNH 










0 1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

1 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

3 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

4 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

5 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

6 0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

Ready 











Note that an array element, like a simple variable, has a value of 0 until it 
is assigned a value. 

The size and number of arrays you can define depends on the amount of 
memory available in your program area. Additional information on arrays 
can be found in Chapter 12. 

It is more efficient to dimension multiple arrays in one statement than to 
have multiple DIM statements. 
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You can place a DIM statement an 3 rwhere in a multi-statement line and 
anywhere in the program. It need not appear prior to the first reference to 
an array that it defines. DIM statements should be placed at or near the 
beginning of a program, however, to make them easy to change. You must 
not have two DIM statements referring to the same variable. 

NOTE 

For compatibility with BASIC-PLUS-2, it is recommended 
that you place the DIM statement before the first reference to 
the array it defines. 

9.7 Mathematical Functions 

Sometimes you need the computer to perform relatively common mathe¬ 
matical operations. You can often find the results of these operations (such 
as sine, cosine, square root, and log) in volumes of mathematical tables. 

Several built-in mathematical functions are available as an optional 
BASIC-PLUS language feature. If your system has these built-in func¬ 
tions, you never have to consult tables or write your own code to find the 
value of the sine of 23 degrees or the natural log of 144. When you need 
these values in an expression, you can substitute the BASIC-PLUS func¬ 
tions. For example: 

S1N(23,*PI/180,> 

LOG(144.) 

The various mathematical functions available in BASIC—PLUS are 
detailed in Table 9-1. These functions return a value in floating-point for¬ 
mat. Note that these functions may not be available on all systems. 

Most of these functions are self-explanatory; the rest are described in the 
following sections. 


9.7.1 Sign Function, SGN(X) 

The sign function returns a value of -i-1 if X is a positive value, 0 if X is 0, 
and -1 if X is negative. For example: SGN{3.42) = 1, SGN(—42) = -1, and 
SGN(23-23) = 0. 

LISTNH 

10 REM - SGN FUNCTION DEMO 

100 READ A.B & 

\ PRINT 'a=';a. 'b=';b 

110 PRINT 'SGN(A)='1SGN(A)» 'SGN<B)=' SGN(B) 

120 PRINT 'SGN(INT<A))='?SGN(INT<A)) 

1000 DATA -7.32. 0.44 

327B7 END 

Ready 

RUNNH 

A=-7.32 B= .44 

SGN<A)=-1 SGN(B)* 1 

SGNdNTCA) )=-l 


Ready 
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Table 9-1: Mathematical Functions 


Function 

Code 

Meaning 

ABS(X) 

Returns the absolute value of X. 

SGN(X) 

Returns the sign function of X, a value of 1 preceded by the sign of X, 
SGN(0) = 0. 

INT(X) 

Returns the largest integer less than or equal to X (INT(-.5) = -1) as a real 
number. 

FIX(X) 

Returns the value of X as an integer with any fractional portion removed 
(FIX(-.5)=0). 

COS(X) 

Returns the cosine of X (X in radians). 

SIN(X) 

Returns the sine of X (X in radians). 

TAN(X) 

Returns the tangent of X (X in radians). 

ATN(X) 

Returns the arc tangent (in radians) of X. 

SQR(X) 

Returns the square root of X. 

EXP(X) 

Returns the value of e^X, where e = 2.71828... 

LOGKX) 

Returns the natural logarithm of X, log^ X. 

LOGIO(X) 

Returns the common logarithm of X, logj^ X. 

PI 

Has a constant value of 3.14159... 

RND 

Returns a random number between 0 and 1. Unless the RANDOMIZE 
statement appears in the program before the RND function, the program 
produces the same sequence of random numbers each time it runs. The 
value of X is ignored and can be omitted. 


9.7.2 Integer Function, INT(X) 


The integer function returns the value of the largest integer not greater 
than X. For example, INT(34.67) = 34. You can use INT to round numbers 
to the nearest integer with the expression INT(X + .5). For example, 
INT(34.67 + .5) = 35. You can also use INT to round to any given decimal 
place, for example: 

INT(X*10,* D+.5)/10.*Dr. 

D is the number of decimal places desired. Consider the following program: 

LISTNH 

10 ! DEMONSTRATION OF INTEGER (INT) FUNCTION 8. 

! INT DOES NOT ROUND TO NEAREST & 

! INTEGER* BUT DROPS THE FRACTION PART 
100 INPUT 'NUMBER TO BE PROCESSED BY INT FUNCTION'*A 

110 INPUT 'NUMBER OF DECIMAL PLACES FDR ROUNDING'5D 

120 PRINT 'TRUNCATED INTEGER*'iINT(A) 

130 PRINT 'ROUNDED INTEGER*'iINT(A+.5) 
lAO PRINT 'ROUNDED TO 'iDi 'PLACES*'! & 

INT(A*10‘D+.5)/(10*D) 

150 PRINT 

160 PRINT 'ENTER ANOTHER NUMBER* TYPE A ZERO TO STOP 

170 INPUT A 

180 IF A <> 0 GO TO 110 

32767 END 

Ready 
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RUNNH 

NUMBER TO BE PROCESSED BY INT FUNCTION? 23.67 
NUMBER OF DECIMAL PLACES FOR ROUNDING? 1 
TRUNCATED INTEGER= 23 
ROUNDED INTEGER= 24 
ROUNDED TO 1 PLACES= 23*7 

ENTER ANOTHER NUMBER» TYPE A ZERO TO STOP -- 
? 456.50505 

NUMBER OF DECIMAL PLACES FOR ROUNDING? 2 
TRUNCATED INTEGER= 456. 

ROUNDED INTEGER= 457 
ROUNDED TO 2 PLACES= 456.51 

ENTER ANOTHER NUMBER# TYPE A ZERO TO STOP -- 
? 0 

Ready 

For negative numbers, the largest integer contained in the number is a 
negative number with the same or a larger absolute value. For example: 
INT(-23)= -23, but INT(-14.39) = -15. 


9.7.3 Random Number Function, RND 

The random number (RND) function produces a random number greater 
than or equal to 0 but less than 1. You can reproduce the numbers in the 
same order for later checking of a program. You do not need an argument 
with the RND fvmction, although you may use one. This argument can 
be any number, since its value is ignored. For compatibility with 
BASIC-PLUS-2, you should not use an argument with the RND function. 


LISTNH 


10 

REM - RANDOM NUMBER DEMONSTRATION 

20 

INPUT "HOW MANY RANDOM NUMBERS"5N 

30 

FOR 1=1 TO N 

40 

PRINT RND# 

50 

NEXT I 

32767 

END 

Ready 


RUNNH 



HOM MANY RANDOM NUMBERS? 13 
.204935 .229581 

.783713 .741854 

.682372 .991239 

Ready 


To obtain random digits from 0 to 9, change line 40 to read: 

40 PRINT INTdO.RND)* 


Then run the program again. The results of the second run are: 


RUNNH 

HON MANY RANDOM NUMBERS? 13 

2 2 5 1 9 

7 7 3 7 B 

6 9 8 

Ready 


.533074 

.397713 

.806084 


.132211 

.709588 


.995602 

.67811 
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You can generate random numbers over any range. In general, if you want 
the range (A,B), use either: 

(B-A)*RND(X)+A 

(B-A)*RND+A 

This produces a random number in the range A<n<B. 


9.7.4 RANDOMIZE Statement 

The RANDOMIZE statement has the form: 

RANDOM[IZE] 

Use the RANDOMIZE statement with the RND function to obtain different 
random numbers every time you run a program. Place RANDOMIZE before 
the first RND function in the program. When executed, RANDOMIZE 
causes the RND function to choose a random starting value, so that the 
same program run twice gives different results. For this reason, it is a good 
practice to debug a program completely before inserting the RANDOMIZE 
statement. 

To demonstrate the effect of the RANDOMIZE statement on two runs of the 
same program, the RANDOMIZE statement appears in statement 15 of the 
following program: 

LISTNH 

10 REM - RANDOM NUMBER DEMONSTRATION 

15 RANDOMIZE 

20 INPUT "HOW MANY RANDOM NUMBERS"5N 

30 FOR 1=1 TO N 

40 PRINT RND» 

50 NEXT I 

327B7 END 

Ready 


RUNNH 

HOW MANY RANDOM NUMBERS? 35 


.541559 

♦249281 

♦621653 

.486387 

.32345 

.5B3214 

♦468236 

♦740494 

.228836 

.708573 

* 191913 

♦774316 

♦918883 

.543249 

.99135 

.058857 

.430996 

♦562B36E~1 

.458616 

.245325 

.344403 

.858497 

♦513523E-1 

.581639 

♦27BB19E 

.931222 

.338373 

♦849245 

.850108 

.257448 

.893713 

.452437E-1 

♦228047 

.961087 

.714104 

Ready 





RUNNH 





HOW MANY 

RANDOM NUMBERS? 12 




♦448782 

.692627 

.116732 

♦466741 

.749863 

.29851 

.422888E-1 

.567144 

♦022262 

.292799E- 

♦975321 

♦588409 





Ready 


The output from each run is different. 
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9.8 User-Defined Functions 

Sometimes you want a program to execute the same sequence of statements 
or mathematical formulas in several different places. BASIC—PLUS allows 
you to define your own functions and call them in the same way you call the 
standard fvmctions, such as RND, SQR, or COS. 

A user-defined function name consists of FN followed by any valid variable 
name. For example: 

FNA 

FNAl 

Because A and A1 are real variables, FNA and FNAl are real functions. 
They return floating-point values. You can also define string functions 
(which return string values) and integer functions (which return integer 
values). To do so, append a string or integer variable name to FN. For 
example: 

FNA$ 

FNAX 

Like variables, functions with the same name but different suffixes are 
different functions. See Chapters 10 and 11 for more information on string 
and integer functions. 

You can define a function anywhere in the program. Write the defining, or 
DEF*, statement as: 


DEF* FN<variable(arguments)> = <expression(argument8)> 


NOTE 

For compatibility with previous versions of BASIC—PLUS, 
DEF is supported as a synonym of DEF*. However, DEF* is 
preferred for compatibility with BASIC-PLUS-2. 


The argiunents in a DEF* statement can consist of zero to five dummy 
variables. The expression, however, need not contain all the arguments and 
can also contain other program variables not among the arguments. For 
example: 

10 DEF* FNA(S) = S*2 


The preceding statement causes line 20 to be evaluated as R=17: 
20 LET R = FNA<4)+1 
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The following example causes the function to be evaluated using the cur¬ 
rent value of the variable X in the program: 

50 DEF» FNB(A»B) = A+X*Z 
60 Y=FNB(14,a .R3) 


The dummy argument in this case (B, which becomes the actual argument 
R3 in the function call) is not used. 


The following two programs illustrate the use of a user-defined fimction. 
The first program uses different variables for the dummy argument in the 
DBF* statement and the actual argument in the function call; the second 
program uses the same variable for both the dummy argument and the 
actual argument. Otherwise, the two programs are identical. Both produce 
the same output. 


Program 1 


LISTNH 

10 ! DEHO OF FUNCTION OEFINITION 

100 DEF» FNS<A)=A*A 

no FOR 1 = 1 TO 5 8. 

\ PRINT I» FNS(I) & 

\ NEXT I 
32767 END 

Ready 


Program 2 


LISTNH 

10 ! DEMO OF FUNCTION DEFINITION 

100 DEF* FNS(I)=I"I 
no FOR 1 = 1 TO 5 & 

\ PRINT I» FNS<I) & 

\ NEXT I 
327B7 END 

Ready 


The output is: 


RUNNH 

1 1 

2 4 

3 27 

4 256 

5 3125 

Ready 
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DEF* statement arguments are dummy variables. When your program 
invokes the defined function, the first value passed in the function call is 
assigned to the first dummy variable. The second value is passed to the 
second dxunmy variable, and so forth. The number of values passed must 
match the number of dummy variables in the DEF’>‘ statement: 


100 

DEF# 

FNA(X) 

= X"2+3#X+4 


200 

DEF* 

FNB(X) 

= FNA(X>/2 + 

FNA(X) 

300 

DEF# 

FNC(X) 

= SQR(X+a) + 

1 


The arguments of a user-defined fimction can be numbers, variables, other 
functions, or mathematical expressions. For example: 

40 LET R = FNA(X+Y+Z)#N/<Y*2+D) 

A user-defined function can have zero to five arguments: 

25 DEF# FNL<X*Y»Z) = S0R(X‘2 + Y*2 + Z*2) 

A later statement in a program containing this user-defined function might 
look like: 

55 LET B = FNL(D.L»R) 

where D, L, and R have some values in the program. 

The number of arguments you use to call a user-defined function must 
agree with the number of arguments that defined it. Otherwise, you get an 
error message. For example: 

10 DEF» FNA (X) = X*2 
20 PRINT FNA(3»2) 

These statements cause the error message: 

?Artfu«ent5 don't match at line 20 

You can use a DEF* statement or function reference, where a function has 
zero arguments, to write the function name with or without parentheses. 
For example: 

LISTNH 

10 DEF# FNA=X*2 

20 INPUT 'TYPE A NUMDER'fX 

30 PRINT FNA* FNAO 

32767 END 

Ready 

RUNNH 

TYPE A NUMBER? 3*35 
13*3225 13.3225 

Ready 
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When you call a user-defined function, you can use any legal expression as 
an argument. BASIC-PLUS substitutes the value of each expression for 
the corresponding fimction variable. For example: 


LISTNH 


10 

DEF* FNZ(X)=X"2 

20 

LET A=2 & 


\PRINT FN2(2+A> 

32767 

END 

Ready 


RUNNH 


16 


Ready 



If you define the same function name more than once, an error message is 
printed: 


100 DEF« FNX(X>=X*2 
110 DEF* FNX(X)=X*4 
?Illedal FN redefinition at line 110 

Ready 


The function variable need not appear in the function expression. For 
example: 


LISTNH 

100 

! FUNCTION VARIABLE 

no 

DEF* FNA<X) = 4*A + 

120 

FOR A = 0 TO 3 

130 

LET R = FNA(IO) + 1 

32767 

\ PRINT R & 

\ NEXT A 

END 

Ready 



NOT IN FUNCTION EXPRESSION 
2 

&C 


RUNNH 

3 

7 

11 

15 

Ready 

The next program contains examples of multi-variable DBF* statements in 
lines 30, 50, and 70. 


LISTNH 

30 

50 

70 

100 

110 

200 

210 

300 

310 

32767 


DEF* FNA(X #Y) = X + Y 
DEF* FNM(X#Y) = X * Y 

DEF* FNU(A >CfD#E) = <(A-B)*C) + (D-A)/(E+4) 

INPUT “2 numbers to ADD”? AtB 

PRINT "The sum of"5 A5 "+"5 B5 "is"; FNA(AfB) 

INPUT "2 numbers to MULTIPLY”; E*F 

PRINT "The product of”; E; ; f; "is"; FNM<E#F) 

INPUT ”5 numbers to play with"; A#B#C#DtE 

PRINT "The unusual result of that is”* FNU(A *B#C#D#E) 

END 


Ready 
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RUNNH 

2 numbers to ADD? 5tS 
The sum of 5 + 6 is 11 
2 numbers to MULTIPLY? 4,5 
The product of 4 * 5 is 20 
5 numbers to play with? B#2#3fl4»8 
The unusual result of that is 1246667 

Ready 


9.9 Subroutines 


A subroutine is a section of code that can be called at more than one point 
in the program. A subroutine can perform a complicated I/O operation for a 
volume of data, a mathematical evaluation, or any number of other opera¬ 
tions. The first line in the subroutine can be a remark or any executable 
statement; the remaining lines in the subroutine perform whatever opera¬ 
tion you specify. 

Like user-defined functions, subroutines let you execute the same sequence 
of instructions at more than one point in a program. Unlike user-defined 
functions, which are called by name, subroutines are called by line number. 

You can use more than one subroutine in a single program. They are nor¬ 
mally placed in line number sequence at the end of the program. 

A useful practice is to assign distinctive line numbers to subroutines. For 
example, if the main program uses line numbers up to 199, use 200 and 300 
as the first numbers of two subroutines. Consider the following subroutine 
that uses both the GOSUB and RETURN statements: 


LISTNH 

10 PRINT “HI THERE." & 

\ GOSUB 1000 t. 

\ PRINT "I'M BACK AT LINE 10” & 

\ GOSUB 1000 

20 PRINT “I'M BACK AT LINE 20 NOW" 8. 

\ GOTO 327B7 

1000 PRINT "JUMPING JEHOSOPHAT!" 8. 

\ RETURN 

32767 END 

Ready 

RUNNH 
HI THERE4 

JUMPING JEHOSOPHAT! 

I'M BACK AT LINE 10 
JUMPING JEHOSOPHAT! 

I 'M BACK AT LINE 20 NOW 


Ready 
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9.9.1 GOSUB Statement 


Subroutines usually are placed near the end of a program before any DATA 
statements and must go before the END statement. The GOSUB statement 
calls the subroutine. Your program continues imtil it encoimters a GOSUB 
statement of the form: 

GOSUB <line number> 

The line number after the word GOSUB is the first line number of 
the subroutine. Control then transfers to that line in the subroutine. For 
example; 

50 GOSUB 200 

Control transfers to line 200 in your program subroutine. 

9.9.2 RETURN Statement 

A RETURN statement is necessary to exit a subroutine. It has the form: 
RETURN 

You use RETURN in the following sequence: 

1. The program encoimters a GOSUB statement. 

2. The system internally records the location of the next executable 
statement. 

3. Control transfers to the subroutine. 

4. A RETURN statement at the end of the subroutine transfers control 
back to where it left off in the main program. 

In this way, no matter how many times you call subroutines, the pro¬ 
gram returns to the right place. For example, refer to the subroutine in 
Section 9.9. 

9.9.3 Nesting Subroutines 

Subroutines can be nested; that is, one subroutine can call another sub¬ 
routine. If the execution of a subroutine encounters a RETURN statement, 
it returns control to the statement after the GOSUB that called the sub¬ 
routine. Therefore, a subroutine can call another subroutine, including 
itself. 

Subroutines can be entered at any point and can have more than one 
RETURN statement. You can transfer to the beginning or to any part of a 
subroutine. Multiple entry points and returns can make a subroutine more 
versatile, although more difficult to debug and maintain. 

The maximum level of GOSUB nesting depends on the size of your program 
and the amount of memory available. Exceeding this limit generates a 
message of the form: 

?MaxlmuM Memory exceeded at line <Iine number> 
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9.10 END Statement 


The END statement is the last statement in a BASIC-PLUS pro¬ 
gram. When executed, it closes all open I/O channels and halts program 
execution. 

While BASIC-PLUS lets you omit the END statement, you should always 
include it to guarantee an orderly end to program execution. 

The END statement has the form: 

END 

Its line number should be the largest line number in the program. Pro¬ 
grammers often place the END statement at line 32767 (the largest line 
number allowed) to guarantee that it is the last line in the program, 

BASIC!-PLUS lets you create a program that has statements after the END 
statement. However, when you run or retrieve this program, BASIC—PLUS 
ignores all statements that follow the END statement. Suppose, for exam¬ 
ple, that you write a program where an END statement is followed by 
additional statements: 

NEW TEST 

Ready 

100 PRINT ‘’HELLO" 

200 PRINT "GOODBYE" 

300 END 

^00 LET C = 5 

500 PRINT C 

You see all the lines when you list the program, but lines 400 and 500 do 
not execute when you run the program. Similarly, you can save the pro¬ 
gram, but lines 400 and 500 are lost when you use the OLD command to 
retrieve the program. For example: 

SAME TEST 
Ready 
OLD TEST 
Ready 
LISTNH 

100 PRINT "HELLO" 

200 PRINT "GOODBYE" 

300 END 

Ready 


You can run a program that does not contain an END statement. 
BASIC-PLUS executes an implicit END statement and does not print an 
error message. However, BASIC—PLUS prints the following message when 
you retrieve a program without an END statement: 

?End of file on device 
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9.11 STOP Statement 


Like the END statement, the STOP statement halts program execution. 
Unlike the END statement, however, the STOP statement does not close 
I/O chaimels. In addition, the STOP statement does not us\ially appear in a 
finished BASIC-PLUS program. Instead, is a debugging tool. STOP lets 
you halt execution at various points in a program to examine variables and 
make changes to the program. 

The STOP statement has the form: 

STOP 

When executed, STOP halts the program and prints: 

Stop at line <line nu«ber> 

Ready 

The <line number> is the line containing the STOP statement. Chapter 6 
of this manual describes the use of the STOP statement in program 
debugging. 

Usage Note 

When you debug an error-handling routine, be aware that STOP resets the 
values of the BASIC—PLUS variables ERR and ERL, which are used in 
error-handling routines. STOP sets ERR (the error number) to 123, which 
is the "Stop at line <line number> ” message. STOP sets ERL, (the line 
where the error occurred), to the line containing the STOP statement. 

See Section 13.7 for information about error-handling routines. 
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Chapter 10 

Strings and String Functions 


This chapter reviews string constants and variables and describes string 
conversion, string input and output, and string functions. 


10.1 Strings 

Chapter 9 describes the manipulation of numeric information. 
BASIC-PLUS also processes information in strings. A string is a sequence 
of ASCII characters treated as a unit. Notice the messages that the INPUT 
and PRINT statements print in Sections 9.3.2 and 9.3.3 with the input and 
output of numeric values. These messages consist of string constants. Just 
as there are numeric constants and functions, there are also string con¬ 
stants and functions. 

10.1.1 String Constants 

BASIC-PLUS lets you use string constants as well as numeric constants. 
String constants are delimited by either single or double quotation marks. 
For example: 

100 LET Y$ = "FILE4" 

200 Bl$ = 'CAN' 

300 IF A» = “YES" GOTO 250 

"FILE4”, 'CAhP and "YES” are string constants. 

10.1.2 String Variables 

You can define variable names for simple strings and also for lists and 
matrices composed of strings (one- and two-dimensional string arrays). Any 
legal variable name followed by a dollar sign ($) is a legal name for a string 
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variable. (Section 8,3.2 describes the rules for forming legal variable 
names.) For example: 

A« 

C7» 

NAME. OF. CUSTOMER* (EXTEND mode only) 

These are simple string variables. Any subscripted variable name followed 
by a dollar sign ($) denotes a string array. For example: 

U$(N> M2$(N) 

C$(M>N) G1$<M»N) 

M and N indicate the position of the array element in the array, 

BASIC-PLUS automatically initializes numeric variables to zero when you 
run a program. Likewise, it initializes string variables to null strings 
(strings containing no characters). 

10.1.3 Subscripted String Variables 

Define string arrays with the DIM statement, as you do for numeric arrays. 
For example: 

100 DIM Sl«(5) 

This statement means that Sl$ is a string array with six elements, S1$(0) 
through Sl$(5), which you access individually. If you do not use a DIM 
statement, BASIC—PLUS assumes that a subscripted string variable has a 
dimension of 10 in each direction (11 elements including zero). Note that 
the dimension of a string array specifies the number of strings, not the 
number of characters in any string. For example, consider that the first 
statements in a program are: 

1050 FOR 1=1 TO 7 & 

\ LET B$< I ) = "PDP-11" 8c 
\ NEXT I 


BASIC-PLUS creates an array B$(n) with 11 accessible elements, B$(0) 
through B$(10). The elements B$(l) through B$(7) are set equal to 
'TDP-11”. The others are null strings: 


LISTNH 

1050 

FOR 1=1 TO 

7 8c 


\ LET B$<I) 

=“PDP-11 

lOBO 

\ NEXT I 

FOR H=0 TO 

10 8c 


\ PRINT t 

32767 

\ NEXT H 

END 


Ready 
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RUNNH 

0 


1 

PDP-11 

2 

PDP-11 

3 

PDP-11 

4 

PDP-11 

5 

PDP-11 

6 

PDP-11 

7 

8 

9 

10 

Ready 

PDP-11 


In general, dimension all arrays to the maximum size that the program 
refers to. 

10.1.4 String Size 

A string can contain up to 32767 characters, but is limited by the amount of 
available memory. 

You cannot use the LINE FEED key to t3rpe a string on two or more termi¬ 
nal lines. To create a string longer than a terminal line, use string opera¬ 
tions (such as concatenation and other operations that are described later). 
Since memory is limited, you can also save strings in disk files. 

10.1.5 Relational Operators 

When you apply relational operators to string operands, the operators indi¬ 
cate alphabetical order. For example: 


55 IF A$(n<A*<I + l) GOTO 100 


A$(I) and A$(I+1) are compared at line 55. If A$(I) occurs earlier in alpha¬ 
betical order than A$(I +1), execution continues at line 100. See Section 
8.4.3.2 for more information on string relational expressions. 


10.2 ASCII String Conversions, CHANGE Statement 

You can reference individual characters in a string with the CHANGE 
statement. It has the form; 


CHANGE I <array name> ( TO f <string variable> ) 
I <8tring variablo J ^ <array name> j 


The CHANGE statement lets you convert either a string into a list of 
numeric values or a list of numeric values into a string. You can convert 
each character in a string to its ASCII equivalent or vice versa. 
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Table D-1 lists the ASCII characters and their corresponding decimal val¬ 
ues. Several ASCII characters have no graphic equivalent; they do not 
cause a character to be printed. 

The following program uses CHANGE to convert a string into a list of 
numeric values. The program stores the numeric values in an integer 
array. 


LISTNH 

1000 REM -- STRING/ASCII CHANGE DEMO 

1010 DIM XX(3) 

1020 LET A$ = "CAT" 

1030 CHANGE A$ TO XX 

1040 XX=XX<0)+XX<3) & 

\ PRINT 'XX='5XX#'THE ARRAY XX IS ' 5 & 

XX(0)5XX<1)»XX(2)fXX(3) 

1050 I IN A CHANGE STATEMENT THE NUMERIC ARRAY t, 

!IS REFERENCED WITHOUT SUBSCRIPTS* AS THIS & 
lEXAMPLE SHOWS* HAVING A SINGLE-VALUE VARIABLE & 
IWITH THE SAME NAME IN THE PROGRAM CAUSES & 

!N0 AMBIGUITY* 

327B7 END 

Ready 

RUNNH 

XX= 87 THE ARRAY XX IS 3 B7 B5 84 


X%(1) through X%(3) contain the ASCII values of the characters in the 
string variable A$. The first element of array X%, X%(0), becomes the 
number of characters in A$. 

If more characters are present in the string variable than are dimensioned 
in the numeric list, the message “?Subscript out of range” is printed. The 
first element of the list (element 0) becomes the number of characters in the 
string and is greater than the dimension of the list. 

Notice that line 1010 creates the four-element array, X%. Use a DIM state- 
nient in this instance. Otherwise, BASIC—PLUS creates a default eleven- 
element array (X%(10)), which wastes space in yoiir memory area. 

Another program that converts a string into a list of nximeric values 
follows: 


LISTNH 

100 DIM AZ(65) 

110 READ B$ 

120 CHANGE B« TO AX 
130 FOR 1=0 TO AZ(0) & 

\ !AX<0) GIVE LENGTH OF STRING 
140 PRINT AX< I > ; & 

\ NEXT I 

200 DATA ABCDEFGHIJKLMNOPORSTUVWXYZ 
32767 END 


Ready 
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RUNNH 

2B 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 
82 83 84 85 66 87 88 89 90 
Ready 


Notice that A%(0) equals 26, the number of letters in the alphabet. 


So far, you have seen how to convert a string into a list of numeric values. 
You can also use the CHANGE statement to convert the numeric (ASCII) 
representation of characters into string characters. 

The following example uses CHANGE to convert an array of ASCII values 
into a string. A%(0) specifies the number of characters in the string. The 
ASCII values for the characters start at A%(1). 


LISTNH 

100 REM -- ASCII NUMBER TO STRING CONOERSION DEMO 
no FOR 1*0 TO 5 8. 

\ READ AX(I) & 

\ NEXT I 

120 CHANGE AX TO B$ & 

\ PRINT B* 

200 DATA 6>65>66»67 i68>69>70 
32767 END 

Ready 

RUNNH 

ABODE 


This program prints ABCDE because the numbers 65 through 69 are the 
ASCII code numbers for A through E. Although the DATA statement con¬ 
tains a value for A%(6), the program does not read it into the array. Thus, 
only five characters (ABCDE) are printed. ASCII 0 (the contents of A%(6)) 
is not a printable character. 


When you use CHANGE to convert an array to a string, you must indicate 
the nvimber of characters in the string. Place this number in the zero 
element of the array. If element zero has a value less than or equal to zero, 
the CHANGE statement generates a zero-length string. 


NOTE 

The CHANGE statement is different from the intrinsic func¬ 
tions VAL(X$) (which converts a number’s string representa¬ 
tion to a number) and NUM$(X) (which converts a number to 
its string representation). See Table 10-1 for information 
about the VAL and NUM$ functions. 
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10.3 String Input 

You can input strings with READ and DATA, INPUT, and INPUT LINE 
statements. 

10.3.1 READ and DATA Statements 

The READ and DATA statements enter string variables into a program. A 
READ statement can appear anjrwhere in a multi-statement line, but a 
DATA statement must be the last statement on a line. 

Here is an example of READ and DATA: 

10 READ A$ » Cf D 
20 DATA 17f 14» 13.4» CAT 


These statements cause BASIC-PLUS to make the following assignments: 

A$ = the character string ”17” 

B = 14 
C = 13.4 

Attempting to read CAT into D causes BASIC—PLUS to print the message: 

?Illedal number at line 10 


You need quotation marks (”) around a string item in a DATA statement 
only when: 

• The string contains a comma 

• Leading, trailing, or embedded spaces within the string are significant 

• Lowercase letters should not be converted to uppercase 


BASIC-PLUS always accepts single or double quotation marks around 
string items, even when they are not necessary. For example, the items in 
line 500 in the following program are acceptable strings: 


LISTNH 

100 READ A».C$>D« .E« 

110 PRINT A«fB$*;C$iD«;E$ 

120 PRINT A»»B$»C$»D*fE* 

500 DATA 'MR. JONES'. MS SMITH. "MRS.BROWN". 'MS'. '"MR"' 
32767 END 

Ready 

RUNNH 

MR* JONESMSSMITHMRS*BROWNMS"MR“ 

MR* JONES MSSMITH MRS*BR0WN MS "MR" 


Ready 
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Although the string MS SMITH is acceptable without quotation marks, 
embedded spaces in the string are discarded. 

BASIC—PLUS stores all values from the programmed DATA statements as 
an ASCII string list. When it reads a numeric variable, BASIC—PLUS per¬ 
forms the appropriate ASCII—to—numeric conversions. When a string varia¬ 
ble is read, the string is used as it appears in the DATA statement. If the 
item is not in quotation marks, BASIC-PLUS ignores leading, trailing, and 
embedded spaces. If the item appears in quotation marks, the string varia¬ 
ble is equated to the string within the quotation marks. 

See Section 9,2.3 for more information about READ and DATA. See also 
the MAT READ statement. Section 12.2. MAT READ reads numeric and 
string matrices. 

10.3.2 INPUT Statement 

You can use the INPUT statement to input strings. For example: 

10 INPUT "YOUR NAME"!N* 

This statement is equivalent to: 

100 PRINT 'YOUR NAME'S 

no INPUT N$ 

When an INPUT statement is executed, it prompts you for input with a 
question mark. To ensure that BASIC-PLUS reads your input correctly, it 
is recommended that you enter no more than 132 characters (including 
commas between values) before you press the RETURN key. See Sections 

9.2.2 and 15.4 for more information about the INPUT statement. 

10.3.3 INPUT LINE Statement 

Besides INPUT, you can also input strings with the statement: 

INPUT LINE <8tring variablo 

For example: 

10 INPUT LINE A$ 

This statement causes the program to accept a line of input from the termi¬ 
nal with embedded spaces, punctuation characters, or quotation marks. 

You cannot print a text string with the INPUT LINE statement. For 
example: 

10 INPUT LINE 'YOUR NAME' 5 A* 

?Syntax error at line 10 

To print a text string, use the PRINT statement. 
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An INPUT LINE statement reads the line as you type it, including the line 
terminating character(s). You can terminate the line in one of the following 
ways: 

1. Carriage returnlline feed —press the RETURN key (appends ASCII val¬ 
ues 13 and 10 to the character string). 

2. Line feed —^press the LINE FEED key (appends ASCII values 10, 13, 
and 0 to the character string). 

3. ESCAPE—press the ESCAPE, ALT MODE or PREFIX key, 
depending on the terminal (appends ASCII value 27 to the character 
string). 

4. Form feed —^press CTRL/L (appends ASCII value 12 to the character 
string). 

When BASIC—PLUS encounters an INPUT or INPUT LINE statement, it 
displays a prompt (a question mark and a space). This signals that the next 
line typed will be treated as input. 

You can enter up to 132 characters. If you enter more than 132 characters, 
BASIC—PLUS may not read them correctly. Your string variable will have 
unpredictable contents. For example: 


LISTNH 

100 PRINT 'ENTER LONG STRING' S. 

\ INPUT LINE & 

\ PRINT & 

\ PRINT A$ 

32767 END 


Ready 


RUNNH 

ENTER LONG STRING 

? »♦/['5;'3":3\PDC\DIJKMNH FFFFFFFFFFFFFFF555555555BB6BB7777888901111122 

2333aaRRFFCD3SWWEERGNNM # fKKLL: : : : : DDDD«#### »***_+ ^- + + + + 000 IKOLBBBB 

3BBFFFFFFFFFFFFFRRRRRRRRR4a44daaB5555BS? SBBSB777777B88B889893111111lUUU 
UYYYYFFFFFFVVVVUBBBBNNNNMMMVV? WCCCSS3SAAAA0Q0SBSSWWWEEDDDa4^4aad-a/:i4^4a 

I l \ !HHHHHBGBGBB7777778888?Line t 

00 lond at line 100 
? HH 

aaaaaaaaaaaaaaaaxxxzxzxx'^ .i!! ihhhhhh 


Ready 


You can also input string information in the form of records with the GET 
statement. See Section 17.3 for further information. 
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10.4 String Output 

Use the PRINT statement to print string data. When a PRINT statement 
includes string values (either alone or with other string and numeric 
values), BASIC—PLUS does not add leading or trailing spaces to the string. 
Only the actual content of the string is printed. If you want to print leading 
or trailing spaces, you must include them in the string when you define it. 
The following example shows how BASIC-PLUS prints strings: 


LISTNH 

100 REM -- STRING OUTPUT DEMO 

200 A*=“PART 1" 

300 B$=“PART 2" 

400 C»=''PART 3" 

500 PRINT a$;b$;c$; 

32767 END 

Ready 

RUNNH 

PART IPART 2PART 3 
Ready 


The use of semicolons to separate character string constants from other list 
items is optional in BASIC-PLUS. However, their use is recommended 
because they make the program more transportable and readable. 


10.5 String Functions 

BASIC—PLUS provides built-in mathematical functions for numeric quan¬ 
tities (for example, SIN and LOG). Similarly, the language offers a set of 
functions to simplify the handling of strings. These functions, described 
in Table 10-1, are particularly useful when dealing with whole lines of 
alphanumeric information input by an INPUT LINE statement. Through¬ 
out Table 10—1, A$ in the immediate mode examples is the string: 
"ABCDEFGHUKLMNOPQRSTUVWXYZ”. 


Table 10-1: String Functions 


Function Code 

Meaning 

LEFT(A$,N) 

Indicates a substring of the string A$ from the first character 
through the Nth character (the leftmost N characters of the string 
A$). For example: 

A$= 'A6CDEFGHIJKLMN0P0RSTUUWKVZ' 

Ready 

PRINI LEFT(A$f7) 

ABCDEFG 


(continued on next page) 
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Table 10-1: String Functions (Cont.) 


Function Code 

Meaning 

RIGHT(A$,N) 

Indicates a substring of the string A$ from the Nth character 
through the last character in A$ (the rightmost characters of the 
string A$ starting with the Nth character). For example: 

PRINT RIGHT ( A$ *20%) 

TUMWXYZ 

MID(A$,N1,N2) 

Indicates a substring of the string A$, starting with character Nl, 
that is N2 characters long (the characters between and including 
the N1 through N1+N2-1 characters of the string A$). For 
example: 

PRINT MID (A$#157.»5X) 

OPQRS 

LEN(A$) 

Returns an integer that indicates the number of characters in the 
string A$ (including trailing blanks). For example: 

+ 

CHR$(N) 

PRINT LEN (A$) 

2B 

Indicates a concatenation operation on two strings. For example, 
''ABC”+*’DEF’ is equivalent to ^ABCDEF”, and +’^34’^+ ^^56” 

is equivalent to ”123456”. 

Generates a one-character string with the ASCII value of N. For 
example, CHR$(65) is equivalent to ”A”. Only one character can be 
generated. 

ASCII(A$) 

Generates an integer that is the ASCII decimal value of the first 
character in A$. For example, ASCII(”X”) is equivalent to 88, the 
ASCn equivalent of X. If B$ = ”XAB”, then ASCn(B$) = 88. 

RAD$(I%) 

Converts an integer to a three-character string. This function lets 
you convert a value in Radix-60 format back into ASCII. (Radix-50 
is explained in the RSTSfE Programming Manual.) 

INSTR(N1A$,B$) 

Indicates a search for the substring B$ within the string A$, begin¬ 
ning at character position Nl. Returns a value of 0 if B$ is not 
in A$. Returns the character position of B$ if B$ is found in A$. 
(Character position is measured from the start of the string, with 
the first character counted as character 1.) For example: 

PRINT INSTR(5% tA$ f'0PM 

15 

SPACE$(N) 

If B$ (the search string) is a null string (B$ = ” "), the INSTR 
fimction returns the value 1. The null string is a proper substring of 
any string; it is treated conventionally as the first element of A$ in 
null string search operations. In addition, if both A$ and B$ are 
null strings, the INSTR function returns the value 1. 

Indicates a string of N spaces; used to insert spaces in a character 
string. 


(continued on next page) 
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Table 10-1: String Functions (Cont.) 


• 

Function Code 

Meaning 


NUM$(N) 

Returns a string of numeric characters representing the value of N 
as a PRINT statement would print it. NUM$(n)=(^ace)n(8pace) if 
n>0 and NUM$(n) = —nCspace) if n<0. For example: 

PRINT NUM$<74G5098702134) 

.74B51E 13 


NUM1$(N) 

Returns a string of numeric characters representing the integer or 
floating-point value N. This is similar to the NUM$ fimction, 
except that no spaces or E-format results are returned. You can use 
it to convert an integer or floating-point value for use as a string 
function operand. For example: 

PRINT NUM1$(PI) 

3o141592B5358979 

• 


This example uses a four-word format, which allows you to carry 
out PI to 15 significant digits. Using a two-word format, PI would 
equal 3.14159. 

Here is another example: 

PRINT NLIM1$ (97.5*30456.23+3.03*5.1 ) 

296376.76154965 

• 

VAL(A$) 

Computes the numeric value of the string of numeric characters A$ 
and returns it as a floating-point number. A$ may include digits, a 
leading plus (-I-) or minus (-), a period (.) and E. For example: 



PRINT VAL('14.3E-5') 

.000143 

If A$ contains a character not acceptable as numeric input with the 
INPUT statement, an error results. 


TIME$(N) 

Where N = 0, this function returns the time of day as a string. For 
example: 



01:30 PM 

Where NoO, the function translates N% into a time string. If the 
run-time system was generated using the 24-hour time option, 
01:30 PM is returned as 13:30 followed by 3 qiaces. TIME? always 
returns an 8-character string. 


DATE$(N) 

Where N = 0, this function returns the current date in the form: 
<day>-<month>-<year>. For example: 

12-AuS-ei 

Note that dates are output using both upper- and lowercase letters. 
When the output device does not generate lowercase letters, the 
ASCII values still imply lowercase. Where NoO, the function 
translates N into a date string. If the run-time system was gener¬ 
ated with the numeric date option, 12-Aug-81 is returned as 



81.08.12. 


(continued on next page) 
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Table 10-1: Siring Functions (Cont) 


Function Code 

Meaning 

STRING$(N1,N2) 

Creates a string of length N1 that consists of characters whose 
ASCII decimal value is N2. For example^ to create a string com¬ 
posed of 10 "A” characters (CHIl$(65)), execute the statement: 


PRINT STRINGi(10#65) 

AAAAAAAAAA 


See Table I>-1 for the decimal values of ASCII characters. 

CVT$$(S$,M) 

Converts the source character string S$ according to the decimal 
value of the integer M. Section 10.5.1 describes this function in 
detail. 

XLATE(S$,T$) 

Translates source string S$ from its existing storage code to a code 
indicated by the table string T$, and retiums the translated form of 
string S$ as the target string. 


A complete description of this function appears in Section 10.5.2. 


10.5.1 CVT$$ Function 

The CVT$$ function manipulates a character string and generates a new 
character string. The output string is converted according to the integer 
value that your program gives. You specify CVT$$ in the form: 

CVT$$ (S$,M%) 
where; 

S$ is the string to convert 

M% is an integer value 

The bits of M% are interpreted as follows: 

1 Trim the parity bit. 

2 Discard spaces and tabs. 

4 Discard carriage return line feed ©, form feed (ED, escape 
rubout (SID, and fill or null characters. 

8 Discard leading spaces and tabs. 

16 Reduce spaces and tabs to one space. 

32 Convert lowercase to uppercase. 

64 Convert square brackets to parentheses; for example, to "(” and 
”]” to 

128 Discard trailing spaces and tabs. 

256 Do not allow alteration of characters inside single or double quota¬ 
tion marks except parity bit trimming. 
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You can use these bits in combination. For instance, if M% is given as 21%, 
the result is the same as if you had used three CVT$$ functions with M% 
values of 1%, 4%, and 16%. 

The value 1% in the CVT$$ function removes the parity bit (most signifi¬ 
cant bit) from each character in the string. Under RSTS/E, characters are 
usually represented with no parity. All comparison of characters assume no 
parity. 

The value 2% removes all space characters (CHR$(32)) and horizontal tab 
characters (CHR$(9)) from the string. Values 8%, 16%, and 128% remove 
only selective occurrences of space and horizontal tab characters. The ter¬ 
minating and excess characters which the value 4% removes in the CVT$$ 
function usually have no informational value in a string. 

For example: 

A $ = " abode ^ " 

TAB 5 spaces 

Ready 

PRINT CgT$$(A$f2I) 
abode 

Ready 

PRINT CgT$$(A$ 
abode 

The value 32% converts all lowercase characters in a string to uppercase. 
This feature is valuable because some terminals transmit both forms of 
alphabetic characters. The lowercase characters are between CHR$(97) and 
CHR$(122); uppercase characters are between CHR$(65) and CHR$(90). 

For example: 

A $ = " a b c d e " 

Ready 

PRINT CMT$$( A$ »327«) 

ABCDE 

The value 64% in the CVT$$ function lets you use parentheses instead of 
square bracket characters as delimiters of a project-programmer number. 

For example: 

A$="C200 #2453" 

Ready 

PRINT CUT$$(A$) 

<200 #245) 
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Use the value 64% when printing account numbers to terminals without 
square bracket characters. Most terminals have parenthesis characters, 
whereas many terminals lack square bracket characters. 

The value 256% in the CVT$$ fimction prevents any alteration of charac¬ 
ters inside quotation marks, except parity bit trimming—set by M%=1%. 
Regardless of other values in the parameter M%, when 256% is included no 
operations are performed in the source string on characters inside quota¬ 
tion marks. 

For example: 


A$="abcde' f9h 'iJK" 

Ready 

PRINT CVT*$(A* »8Z+32T.+256X) 

ABCDE' fSh 'UK 

Generally, the precedence of operations that BASIC—PLUS performs on the 
string is in increasing order of the values in the parameter M%. (The 256% 
value, however, is the exception; its precedence ranks between 1% and 2%.) 
This order implicitly determines which operations are performed on the 
string. 

For example, consider the case where characters in the source string have 
their parity bit set, and you do not select the parity trimming option. Sub¬ 
sequent comparisons required by other options might not be successful, 
because the system compares source characters with ASCII characters that 
lack parity. A space (SP) character in no parity or odd parity form 
(CHR$(32)) does not equal a space (SP) character in even parity form 
(CHR$(160)). 

In some text processing applications, the parity bit of each character func¬ 
tions £is a flag instead of a parity bit. It is important in such cases to keep 
the parity bit in the input character of the string. BASIC—PLUS does not 
change or discard these flagged characters if you do not select the parity 
trimming option. 

The precedence of operations affects the result of values given in the 
CVT$$ function. If you give the values 2% or 8% in the CVT$$ function, the 
values 8%, 16%, and 128% have no effect on the output string. Because the 
first option performed (2%) removes all space and tab characters from the 
string, the remaining values dealing with space and tab characters have no 
effect. 

In like manner, the value 16% applies to all space and tab characters not 
discarded by the 2% and 8% options. Thus, to maintain at least a single 
space interval in a string, your program must give the 16% value and omit 
the 2% and 8% values. 

The CVT$$ function often eliminates the need for special code in 
BASIO-PLUS programs to handle string input. For example, the following 
program manipulates an input string at lines 1020 through 1050. 
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LISTNH 

10 EXTEND ! USE BASIC-PLUS EXTEND MODE & 

900 DIM IN»CHARSX( 1287:) t OUT ♦ CHARSX ( 128X ) & 

! DIMENSION TWO ARRAYS TO HANDLE THE BYTE REPRESENTATION & 

! OF THE INPUT AND OUTPUT STRINGS* & 

1000 PRINT “This program uill remote all leading spaces and tabs" & 

\ PRINT "from a strins# and conuert all characters to uppercase*" 8. 

\ PRINT 8c 

1010 PRINT "Your strinS"? 8c 

\ INPUT LINE IN*STRING$ 8c 

1015 ! & 

! LINES 1020 - 1050 PERFORM THE CONVERSIONS 8c 

1020 CHANGE IN*STRING$ TO IN*CHARSI 8c 

! CONVERT THE INPUT STRING TO BYTES 8c 
\ IN*LENT. = IN*CHARS7:(07;) L 

! REMEMBER THE LENGTH OF THE INPUT STRING 8c 
\ 0UT*PTR7; = OX 8c 

! INITIALIZE THE OUTPUT CHARACTER POINTER & 

1030 GOTO 1040 UNLESS IN ♦ CHARSX ( IN * PTRX ) =9X OR IN*CHARSX ( IN * PTRX ) =32X 8c 
FOR IN*PTRX=1X TO IN.LENX & 

! SKIP OVER ALL LEADING TABS (9) AND SPACES (32)* LEAVE 8c 
I THIS LOOP WHEN WE ENCOUNTER A SIGNIFICANT CHARACTER 8c 
! OR THE END OF THE STRING* 8: 

1040 FOR IN*PTRX = IN*PTRX TO IN*LENX 8c 

! NOW COPY ANY REMAINING CHARACTERS IN THE INPUT STRING» 8 
I CONVERTING TO UPPERCASE# AS NECESSARY* 8 
\ OUT*PTRX = OUT*PTRX + IX 8 

! POINT TO THE NEXT OUTPUT CHARACTER* 8 
\ IN.CHARX = IN*CHARSX(IN*PTRX) 8 

! GET A CHARACTER FROM THE INPUT STRING* 8 
\ IF IN*CHARX >= 97X AND IN*CHARX <* 122X THEN 8 

I IF CHAR IS BETWEEN LOWERCASE “A" AND "2“ THEN 8 
OUT*CHARSX(OUT*PTRX) = IN*CHARX - 32X 8 

! MAKE THE CHARACTER UPPERCASE* NOTE 8 
! THAT ASCII (LOCASE CHARACTER)-32 EQUALS 8 
! ASCII (UPCASE CHARACTER). 8 

ELSE OUT*CHARSX(OUT*PTRX) * IN.CHARX 8 

! IF THE CHARACTER IS NOT LOWERCASE# THEN 8 
! COPY IT DIRECTLY* 8 

1050 NEXT IN.PTRX 8 

I GO GET THE NEXT CHARACTER 8 
\ OUT*CHARSX(OX) = 0UT.PTRX 8 

! SET THE LENGTH OF THE NEW STRING* 8 
\ CHANGE OUT.CHARSX TO OUT*STRING« 8 

! CONVERT THE BYTE REPRESENTATION TO A STRING* 8 

1060 PRINT 8 

\ PRINT "The old string was =>"5 IN*STRING$# 8 
\ PRINT "The new string is ==>"; 0UT*STRING$5 8 

! PROVE THAT THE CONVERSION WORKED* NOTE THAT THE 8 
! CARRIAGE RETURN AND LINE FEED THAT THE USER TYPED 8 
! WILL BE PRINTED HERE# SINCE THEY ARE A PART OF THE 8 
! STRING* 8 

327B7 END 


Ready 
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RUNNH 

This program will remoue all leading spaces and tabs 
from a strins» and conuert all characters to uppercase* 

Your string? Thio STrin^ WILl be fixeD 

The old strinS was => This STrins WILl be fixeD 

The new strinS is ==>THIS STRING WILL BE FIXED 

Ready 


You can replace lines 1020 through 1050 with a single CVT$$ function at 
line 1020, as shown in the following sample code. The value of 40% 
(32%+8%) in the CVT$$ function in line 1020 produces the same results as 
lines 1020 to 1050 in the original program. 


LISTNH 

10 EXTEND ! USE BASIC-PLUS EXTEND MODE & 


1000 PRINT "This prcSraw will remoue all leadinis spaces and tabs'* & 

\ PRINT "from a strins> and convert all characters to uppercase*'* fie 
\ PRINT fie 

1010 PRINT "Your string"? &: 

\ INPUT LINE IN*STRING$ fie 


1015 ! fie 

I DO THE CONVERSION AT LINE 1020 fie 

1020 OUT*STRING$ = CVT$$ ( IN•STRING$t 321+BX) fi: 

! CLEAN UP THE INPUT STRING: fie 
! 32 = CONVERT TO UPPERCASE# AND fi. 

! 8 = DISCARD LEADING SPACES AND TABS fi. 

1060 PRINT fie 

\ PRINT "The old strinS was =>"5 IN*STRING$; fi. 

\ PRINT "The new strinS is = = >"; OUT*STRING$; 6: 

! PROVE THAT THE CONVERSION WORKED* NOTE THAT THE fic 
! CARRIAGE RETURN AND LINE FEED THAT THE USER TYPED fi. 

I WILL BE PRINTED HERE# SINCE THEY ARE A PART OF THE fi. 
I STRING* fie 


32767 END 


Ready 


RUNNH 

This program will remove all leading spaces and tabs 
from a strini^# and convert all characters to uppercase* 

Your strini^? con Vert THis strinG TO ALL caps 


The old strins was => convert THis 

The new strinS is ==> CONVERT THIS STRING TO 


strinG TO ALL caps 
ALL CAPS 


Ready 
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10.5.2 XLATE Function 


The XLATE function translates a string from one storage code into 
another, using a translation table that you supply. For example, while 
reading a magnetic tape file, you may need to translate data from EBCDIC 
code to ASCII code so that it can be processed by the PDF—11. 

The XLATE function has the form: 

XLATE (<8tringl> ,<string2> ) 

The first argument, <stringl> , is the source string; the second argument, 
<string2>, is the table string. XLATE returns a string value called the 
target string. 

To perform the XLATE function, BASIC-PLUS operates sequentially on 
the characters in the source string. BASIC—PLUS uses the numeric value of 
each character (0 to 255) as an index into the table string. (Zero means the 
first character, 1 means the second, and so forth.) 

For each character in the source string, BASIC—PLUS looks up the index 
value in the table string. If the selected character in the table string is not 
zero and if the index value is in the table, BASIC—PLUS appends the char¬ 
acter value from the table string to the target string. BASIC-PLUS does 
not transfer any character to the target string if these two conditions are 
not met. Thus, the target string is equal to or shorter than the sovirce 
string. In addition, the target string cannot contain null characters (ASCII 
code 0). 

For example, suppose the first character in the source string is an upper¬ 
case A (ASCII code 65). BASIC—PLUS looks at the sixty-fifth character in 
the table string. If it is an uppercase A, BASIC-PLUS transfers an A to the 
first position in the target string. If it is another character (for example, an 
asterisk), BASIC)—PLUS transfers that character into the first position in 
the target string. BASIC—PLUS does not transfer any character into the 
first position of the target string if the sixty-fifth character in the table 
string is a zero or if the table string contains fewer than 65 characters. 

The following program uses the XLATE function to translate all lowercase 
letters in a string to uppercase and to remove characters other than letters 
or digits. Uppercase letters and digits do not change. 


& 

& 

8c 

200 TABLE* = STRING«(48%>0%) !Do not translate CHR*(0Z) throush "/" & 

+ "0123456789" IKeep dibits the same 8< 

+ STRI NG$ (7X *0‘/.) !Do not translate through & 

+ ”ABCDEFGHIJKLIiNOPORSTUMWXYZ” !Keep uppercase letters the sameftc 
+ STRING$(BX #07.) !Do not translate "C” throui^h “ '" & 

+ "ABCDEFGHIJKLMNOPORSTUVWXYZ" ‘Translate lowercase letters & 

!to uppercase S: 

(continued on next page) 


50 EXTEND 


100 


Build the table strins* (For each place that a zero 
appears in the table string# the character in that 
position will not appear in the target strins*) 
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liable ends here^ Characters •'<*' throuifh <RUBOUT> (CHR$(127%> & 
iwill be left out of target string by default* & 

I 

300 PRINT Be 

\ INPUT "String to translate ”5TEST♦STRING$ !Get user's test string & 

\ GOTO 32767 UNLESS LEN (TEST ♦ STRING$) <> 01 IQuit if user types <RETURN> &c 

dOO TRANSLATED*STRING$ = XLATE(TEST♦STRING$#TABLE$) {Translate test string & 

500 PRINT “The strins you entered translated to "5TRANSLATED♦STRING$5 & 

\PRINT &e 

NREMOMEDtCOUNTX = LEN(TEST *STRING$) - LEN(TRANSLATED *STRING$) & 

\PRINT CHR$<71) IREriOMED*COUNT15" error characters rewoued'*; & 

IF REM00ED*C0UNT1 <> 01 & 

\PRINT L 
\GOTO 300 
32767 END 


RUNNH 

Strins to translate? abedef*123ABC 
The string you entered translated to ABCDEFG123ABC 
3 error characters removed 


10.6 User-Defined String Functions 

You can define your own string functions with the DEF* statement. Write 
string functions like numeric functions (see Sections 9.9 and 13.1). Indicate 
the function as a string function with a dollar sign ($) after the function 
name. 

User-defined string functions return string values. For example, the follow¬ 
ing multi-line function returns the string that comes first in alphabetical 


order: 



100 

DEF* FNF$(A$*B$) 

8c 


\ FNF$ = A$ 8c 



\ IF A$>B$ THEN 

FNF$=B$ 

no 

FNEND 



See Section 13.1 for more information about multi-line fimctions. 

The following function combines two strings into one string: 

10 DEF» FNC$(X*»Y»)=X*+Y* 

String functions can have both numeric and string arguments. However, 
you cannot use numbers as arguments in a function where strings are 
expected or vice versa. Line 80 is unacceptable because FNA$ is defined to 
have a string argument: 

10 DEF# FNA*(A$) = CHR*(LEN<A»)+1) 

80 LET Z=FNA*(4) 

BASIC-PLUS prints: 

?Ar*uments don't match at line 80 
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A function can have arguments of mixed types. BASIC-PLUS converts 
integers to floating-point numbers (and vice versa) when it needs an argu¬ 
ment. Integer and floating-point values, however, are not interchangeable 
with strings. (See Chapter 11 for information on integer and floating-point 
operations.) 

The following example defines a function with a string argument, a 
floating-point argument, and an integer argument: 

DEF* FNA$(A$ >BX >C)=A*+''(''+NUH1*(BX) + " > is ”+NUMl$(C)) 

You can call this function with either of these statements: 

XI* = FNA* (A* » P, 3%) 

XI* = FNA* (A* » PZ» 3 > 

By comparison, the next statement is incorrect because the arguments are 
not in the right order; 

XI* = FNA* (P» A*f 3) 

The following code is a string function that returns the leftmost five charac¬ 
ters from the sum of three arguments: 

LISTNH 

75 DEF* FNA*(X.Y»Z) = LEFT (NUN*(X+Y+Z>»5> 

80 PRINT FNA*(100#20 .3) 

32767 END 

Ready 

RUNNH 

123 

Ready 

NUM$(123) is the five-character string: 

'Xspace)123(space)” 

10.7 String Arithmetic 

The optional string arithmetic feature consists of six functions that treat 
strings of nvuneric characters as arithmetic operands. String arithmetic 
offers greater arithmetic precision with large numbers and fractions than 
floating-point arithmetic. Thus, it eliminates the need for scaling. 

Table 10—2 describes the six functions that make up the optional string 
arithmetic feature: SUM$, DIF$, PROD$, QUO$, PLACE$, and COMP%. 

The arguments A$ and B$ in these functions can be string constants, string 
variable names, or string expressions. Specify strings that consist of 
numeric characters vuth an optional leading sign and an optional decimal 
point. A$ and B$ can each be up to 56 characters long, including the plus or 
minus sign and the decimal point. 
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Remember to end numeric string variable names with a dollar sign ($) and 
to enclose numeric string constants in single or double quotation marks. 

The P% argument is an integer expression that specifies the level of preci¬ 
sion. See Section 10.7.1 for more information. 

Table 10-2: Optional String Arithmetic Functions 


Function Code 

Meaning 

SUM$(A$,B$) 

Yields the arithmetic sum A$ + B$ of numeric strings A$ and B$. 
For example: 

31$= '123aS. 1780' 

Ready 

DIF$(A$,B$) 

PRINT SUM$(S1$>'39*45^5454545') 

12438.G334454545 

Yields the arithmetic difference, A$-B$, of numeric strings A$ 
and B$. For example: 

5$= '9876.54321' 

Ready 

PROD$(A$,B$,P%) 

PRINT DIF$(B$ 78.39') 

9797.B5321 

Yields the product, A$ times B$, rounding to P places. For 
example: 

A$='12345.3780' 

Ready 

S$= '9876.54321 ' 

Ready 

QUO$(A$,B$,P%) 

PRINT PR0D$(A$ tbi »S) 

121932631.112635 

Yields the quotient, A$ divided by B$, with rounding to P places. 
For example: 

C$= '3.5' 

Ready 

V9$ = 0U0$(C$ »'1 .7777' .3) 

Ready 

PRINT V9$ 

1.969 


(continued on next page' 
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Table 10-2: Optional String Arithmetic Functions (Cont.) 


Function Code 

Meaning 

PLACE$(A$,P%) 

Rounds A$ to P places. For example: 


A$= M2345.67BS ^ 


Ready 


PRINT PLACE$(A$,3) 

COMP%(A$,B$) 

12345.679 

Yields a truth value based on the result of a numeric comparison: 

-1 if A$ <B$ 

Oif A$ = B$ 
lif A$ > B$ 


For example, if A$ has the same value as in the previous example 
and Al$ is equal to PLACE$(A$,3): 


PRINT C0NP7.< A$ .Al$) 

-1 


Ready 


PRINT C0MP7(Ai$.A$) 

1 


10.7.1 String Arithmetic Precision 


In SUM$ and DIF$, the precision of the larger argument determines the 
precision of the result. For example: 

10 A$ = ••89516*332948G61‘' 

20 = ••3802.59619" 

30 PRINT SUM$(A$»B$) 

32767 END 
RUNNH 

93118.929138661 


The result is expressed to the precision of A$, the more precise argument. 

10 A$ = ••89516.332948661" 

20 B$ = "3602.59619" 

30 PRINT DIF$<A$»B$> 

32767 END 
RUNNH 

85913.736758661 


The result is expressed to the precision of A$, the more precise argument. 

The PROD$, QUO$, and PLACE$ functions let you specify the level of 
arithmetic precision you want in their results. You specify the level of 
precision with the P% argument. 
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P% is an integer expression. It can be positive or negative. A positive P% 
value less than 5000 rounds the result to P significant digits to the right of 
the decimal point. For example; 


LISTNH 

100 EXTEND 

lALLOWS LONG VARIABLE NAMES 

110 INPUT 'ENTER TUO NUMERIC STRINGS TO BE MULTIPLIED' 58. 

STRING. A* fSTRING.B* 6. 

\ INPUT 'TO HOW MANY DECIMAL PLACES'SPNOZ 
120 PR« = PROD$(STRING. A$ »STRING.B$ »PN0X) 8. 

\ PRINT 'ANSWER IS 'iPR* 

32767 END 

Ready 

RUNNH 

ENTER TWD NUMERIC STRINGS TO BE MULTIPLIED? 56453*346 ♦ '879*0004532' 

TO HOW MANY DECIMAL PLACES? 12 
ANSWER IS 49622516*718654072 


Ready 

RUNNH 

ENTER TWO NUMERIC STRINGS TO BE MULTIPLIED? * 00009067543#0134♦2340345 
TO HOW MANY DECIMAL PLACES? 10 
ANSWER IS *0121717288 

Ready 


You can use a negative P% value if you want an approximate result. For 
example: 

100 PRINT 'ENTER A LARGE NUMBER' & 

\INPUT A$ 8c 
\IF A$ = '0' THEN 150 
110 LET B$ = SUM$(A$»B$) Sc 

! ACCUMULATE TOTAL OF INPUT STRINGS 
120 GO TO 100 

150 B$ = PLACE$(B$»-BZ) 

160 PRINT 'TOTAL IS APPROXIMATELY '; B$5 ' MILLION' 

32767 END 


You can also use the following statement in place of lines 150 and 160: 

150 PRINT 'TOTAL IS APPROXIMATELY ' ; PL ACE$ (B$ #-67.) ; ' MILLION' 


To truncate a result instead of rounding it, specify P% in the form: 

P% + 10000% 

For example, in the following PROD$ function, a P% value of 10012% trun¬ 
cates the result to 12 significant digits to the right of the decimal point: 

10 A$ = ”80516*332948661“ 

20 B$ = ”3602*59619“ 

30 P7. = 100127 

40 PRINT PR0D$(A$fB$fP7) 

32767 END 
RUNNH 

322491200*023617584201 
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When P% is negative, the result of P% + 10000% can be in the range 0 to 
10000. To distinguish between a large value of P and truncation after scal¬ 
ing, BASIC-PLUS compares P% to 5000. The result is rounded if P% is less 
than 5000. Otherwise, the result is divided by lO'^P and trimcated. 

Negative P% causes the result to be effectively divided by lO^P and 
rounded P places to the left of the decimal point. 

To illustrate, the following examples compare the results you get when you 
specify positive and negative P% values with the same arguments: 

10 A$ = ”89516.3329486G1" 

20 B$ = ”3602.59610*' 

30 PX = 14Z 

40 PRINT PR0D$<A$tPX) 

32767 END 
RUNNH 

322401200.02361758420159 


10 A$ = ”89516.332948661" 
20 = ”3602.59619” 

30 PX = -II 

40 PRINT PR0D$<A$fB$>PX) 

32767 END 

RUNNH 

32249120 


10 A$ = "89516.332948661" 
20 PX = 4X 

30 PRINT PLACE$<A$>PX) 

32767 END 

RUNNH 

89516.3329 


10 A$ = ”89516.332948661” 

20 PX = -3X 

40 PRINT PLACE$<A$ tPX) 

32767 END 

RUNNH 

90 


The following examples show results obtained for P% values between 5000 
and 10000: 

10 A$ = "89516.332948661” 

20 B$ = ”3602.59619” 

30 PX = 5500X 

40 PRINT 0U0$(A$»B*>PX) 

32767 END 
RUNNH 
0 


10 A$ = ”89516.332948661” 

20 PX = 9997X 

30 PRINT PLACE$(A$#PX) 

32767 END 

RUNNH 

89 
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If you specify a value outside the range for P%, you receive the error mes¬ 
sage ”%Floating point error at line n.” BASIC-PLUS returns the result 
with as much precision as possible. For example: 

100 A$ = '2' 

200 B$ = '3' 

300 PRINT QU0$(A$#B$fSO) 

327B7 END 
RUNNH 

XFloatinS point error at line 300 

.86G6666G666666666B6G6666666666666B666e6666G66666666G6666 

Table 10-3 summarizes the values of P% and their effects on Y$ (the value 
returned by PROD$, QUO$ and PLACE$). 


Table 10-^: Precision Values in PROD$, QUO$, and PLACE$ 
Functions 


Value of P% 

Effect on Y$ 

0 < = P% < 5000 

Y$ is rounded P significant digits to the right of the decimal 
point. 

P% = P% + 10000 

Y$ is truncated P significant digits to the right of the decimal 
point. 

P% < 0 

Y$ is divided by 10"P and rounded. 

5000 < = P% < 10000 

Y$ is divided by lO^P and truncated. 


10.7.2 Combining String Arithmetic Functions 

You can nest string arithmetic functions (as operands in other string arith¬ 
metic functions, for example) to specify complicated arithmetic or algebraic 
operations. For example, consider the following LET statement: 

X = A*B + C/D 

You can write this in string arithmetic as: 

X$ = SUM$(PR0D*(A$»B$.10)* OUO*(C*.0$.10)) 

The following statement is legal, but it concatenates the product and quo¬ 
tient strings instead of summing them: 

X$ = PR0D*<A» .B$ .10) + QU0$(C* .0$.10) 
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The following program illustrates these two ways of combining string 
functions: 


LISTNH 

100 A$=“12t” lEOALUATE (12*3.3) + (10/4) 

no B$="3.3” 

120 C$="10." 

130 

190 I 

200 X$=SUM$ (PROD$(A$no.)> QUO$(C$»D$#10.)) !THE RIGHT WAY 

210 PRINT "DOING IT THE RIGHT WAY^ X$="; X$ 

220 ! 

300 X$ = PROD$( A$ #B$nO. ) + 0U0$ (C$ #D$ #10 ♦ ) ! THE WRONG WAY 

310 PRINT "DOING IT THE WRONG WAY# X$="; X$ 

320 ! 

327G7 END 


Ready 


RUNNH 

DOING IT THE RIGHT WAY# X$=42.1 
DOING IT THE WRONG WAY# X$*39.62.5 


Ready 
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Chapter 11 

Integer and Floating-Point Operations 


BASIC-PLUS has two numeric data t 3 rpes: floating-point numbers and 
integers. Floating-point numbers can have fractional parts; integers are 
whole numbers. This chapter describes the operations you can perform 
using these two data t 3 ^es. 

Topics include: 

• Integer arithmetic 

• Logical operations on integers 

• Floating-point and scaled arithmetic 

• Mixed-mode arithmetic 

11.1 Introduction to Integers 

BASIC—PLUS stores integer data in binary form. Each integer uses one 
PDP—11 16-bit word of memory. 

Integers have two characteristics you can take advantage of in 
BASIC-PLUS programming: 

1. They are numbers. 

2. They are bit patterns. 

As numbers, integers can range in value from -32768% to 32767%. Integers 
are useful as counters in program loops and other repetitive operations. 
Your programs will be smaller and more efficient if you use integers for 
arithmetic operations that involve whole numbers in the range -32768% to 
32767%. Integers use less space than floating-point numbers, and integer 
arithmetic is faster than floating-point arithmetic. For information on inte¬ 
ger arithmetic, see Sections 11.3 through 11.6 of this chapter. 
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Like everything else inside a computer, an integer is a bit pattern. Each 
integer value corresponds to a unique sequence of bits that have either the 
value 1 or 0. A bit whose value is 1 is *'on” or "set”; a bit whose value is 0 is 
"off’ or "clear.” 

BASIC-PLUS uses integers as bit patterns to perform logical operations 
(such as determining whether a logical expression is true or false). In addi¬ 
tion, BASIC—PLUS gives you access to this process as a programming tool. 
By performing logical operations on integers, you can test and manipulate 
individual bits inside a PDP-11 16-bit word. Section 11.7 describes 
the technique, which has several usefiil applications in BASICJ-PLUS 
programming. 

Whether you use integers as numbers or as bit patterns, you always specify 
them to BASIC-PLUS as positive or negative decimal numbers, and 
BASIC5-PLUS always returns them to you in the same form. 

While working with integers as decimal numbers is natural when you use 
them to do arithmetic, you need to do some "translation” when you use 
them as bit patterns. The next section gives you the information you need 
to make that translation. It also explains why integer arithmetic in 
BASIC-PLUS works the way it does. 

11.2 Internal Integer Format 

This section explains how an integer is stored in memory. If you plan to use 
integers only in arithmetic operations, you may want to skip this section 
for now. But if you plan to use integers in logical operations, read this 
section before you read Section 11.7. 

Figure 11-1 shows the internal format of an integer. 

Figure 11—1: Internal Integer Format 

BIT 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 


HIGH BYTE LOW BYTE 

The first 15 bits (0 through 14) each correspond to a positive power of 2. For 
example, a value of 1 in bit 0 means 1% (2^0), a value of 1 in bit 3 means 8% 
(2''3), and a value of 1 in bit 8 means 512% (2''8). 

Bit 15, the leftmost bit, has a special purpose: it stores a number’s sign. 
Thus, it is called the "sign bit.” A value of 0 in the sign bit means a number 
is positive; a value of 1 in the sign bit means a number is negative. 

Bits 0 through 7 are called the "low byte” or the "low order bits”; bits 8 
through 15 are called the "high byte” or the "high order bits.” (You will 
encounter these terms later in this manual; they are also used in the 
RSTS/E Programming Manual.) The low byte can store a value in the 
range 0% through 255%; the high b 3 d;e can store a value in the range 512% 
through 32512%. 
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A word that contains values of 1 in bits 0 through 14 (and 0 in bit 15) stores 
the value 32767%, the largest value an integer can have in BASIC-PLUS. 
A word with all bits set to 0 stores the value 0%. 

Each integer value has a unique bit pattern. To find the value of an integer 
from its bit pattern, you add the powers of 2 that correspond to each of the 
"1” bits. For example, consider a word where bits 0, 3, and 8 are 1 and the 
rest of the bits in the word are 0. The bit pattern is: 

0000000100001001 

The integer value stored in this word is l% + 8% + 512%, or 521%. The 
number is positive because the sign bit is 0. 

You use the same process for negative numbers. The key to deciphering 
negative numbers is the sign bit. The sign bit has value as well as sign; its 
value is -32768%. 

The following example shows how to determine the value of a negative 
number from its bit pattern. The internal format for the integer value -1% 
is; 


BIT 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
1111111111111111 


The integer value -1% has "all bits on.” To see why, add the values of all 
the bits. Bit 15 has the value -32768%; the rest of the bits are positive 
powers of 2 and add up to 32767%. The result is -1%. 

The sign bit has the value -32768% because the PDP—11 computer does 
calculations using numbers in their "two’s complement” form. (A binary 
number’s "two’s complement” is its value with all the bits reversed, plus 1.) 
This method allows arithmetic to be done inside the machine as a continu¬ 
ous operation, regardless of whether numbers are positive or negative. 

Two’s complement arithmetic has the following characteristics: 

• There are 32,768 positive integers: 0% to 32767%. 

• There are 32,768 negative integers: —1% to -32768%. 

• When 1 is added to the highest number in the range, the result is the 
lowest number. For example, 32767% -i- 1% yields -32768%, the value of 
the sign bit. (You can use this expression in certain statements to set a 
word’s sign bit. Setting the sign bit causes the system to perform special 
functions. See Section 14.5.3.1 for an example.) 

The next four sections describe the arithmetic operations you can perform 
using integers as whole numbers. In Section 11.7, which describes logical 
operations on integers, you will see how to use integers as bit patterns. 
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11.3 Integer Constants and Variables 

Numeric variables and constants without a % suffix are stored internally as 
floating-point numbers. When operations deal with whole numbers, you 
can achieve significant economies in storage space and execution time with 
the integer data type, which uses only one computer word per value. Inte¬ 
ger arithmetic is also significantly faster than floating-point arithmetic. 
Integer variables can assume values in the range -32768% to + 32767%. 
Integer constants can assume values in the range —32767% to +32767%. 

You specify that a constant, variable, or function is to be an integer by 
ending its name with the % character. For example: 

AZ lOOZ FNXZ(Y> 

AIZ 4Z FNLZ(NZ»LZ) 

When you assign a floating-point value to an integer variable, the frac¬ 
tional portion of that number is lost. The number is not rounded to the 
nearest integer value. (A FIX function is performed rather than an INT 
function; see Section 9.8.) For example: 

AX » 1.1 
AZ = 1.9 

Either of these would assign the value 1 to A%. 

11.4 Integer Arithmetic 

In integer arithmetic, the number range -32768 to + 32767 is treated as 
continuous, with the number after + 32767 equal to -32768. But adding 
large positive numbers can result in unexpected negative numbers, as in 
32767% +2% = -32767%. 

Integer division forces truncation of any remainder; for example b%n% = 0 
and 199%/100%=1. Integer and floating-point data can be freely mixed in 
such operations (see Section 11.9). The answer is stored in the format indi¬ 
cated as the resulting variable. For example: 

125 LET XZ = NZ + FNA(R)*2. 

BASIC—PLUS evaluates the expression to the right of the equal sign and 
then tnmcates the result to provide an integer value for X%. 

Where program size is critical, use the % character to generate integer 
values because it uses significantly less storage space. For example: 

120 FOR IZ = IX TO lOX 

This statement takes less storage space and executes faster than: 

120 FOR I = 1 TO 10 


11—4 Integer and Floating-Point Operations 






11.5 Integer I/O 


Input and output of integer variables is performed in exactly the same 
manner as input emd output on floating-point variables. (Remember that 
where a floating-point variable has an integer value, BASICJ-PLUS auto¬ 
matically prints it as an integer. The value is still stored internally as a 
floating-point number, however, thus taking more storage space.) 

It is illegal to provide a floating-point value for an integer variable through 
either a READ or INPUT statement. For example: 

LISTNH 

110 READ AX & 

\ PRINT AX 
BOO DATA 2.7 
32767 END 

Ready 

RUNNH 

XOata format error at line 110 
Ready 

Change line 600 to: 

600 DATA 3 
The result is: 

RUNNH 

3 

Ready 


11.6 User>Deflned Integer Functions 

You can write functions to handle integer vsiriables as well as floating¬ 
point variables. You define an integer function by ending its name with the 
% character. 

For example, you can define a function that returns the remainder when 
one integer is divided by another: 

no DEF FNRX(IX»JX) = IX-( (IX/JX) ♦ JX ) 

You can call this function later in the program as: 

200 PRINT FNRX(AX*11X) 
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You can use integer arguments where floating-point arguments are 
expected and vice versa. BASIC-PLUS performs the necessary conversions. 
You cannot, however, use strings and numbers interchangeably. 

75 DEF FNAKXX) = XZ - IX 
80 LET 2X = FNAX(12.34) 

This example is acceptable. Z equals 11 after line 80 has been executed. 

11.7 Logical Operations on Integer Data 

So far, you have learned how to use integers as whole numbers in 
mathematical calculations. You can also use integers eis logical values in 
BASIC-PLUS. 

BASIC-PLUS produces logical values when it evaluates expressions that 
contain: 

• Relational operators, such as = and < 

• Logical operators, such as AND, OR, and XOR 

These operators cause BASIC-PLUS to compare two operands and store the 
result of the comparison in a one-word integer variable. This result is a 
logical value. 

11.7.1 The Logical Values -1% and 0% 

If you have written programs with IF-THEN statements, you have already 
used the logical values -1% and 0%. You know these values as "true” and 
"false.” 

BASIC—PLUS uses —1% (all bits on) to mean "true” and 0% (all bits off) to 
mean "false.” Two types of expressions always return one of these two 
values: 

• Relational expressions 

• Logical expressions that compare two relational expressions 


11.7.1.1 Relational Expressions 

In evaluating a relational expression, BASIC—PLUS compares two num¬ 
bers or two string values. The comparison has two possible results: the 
logical value —1% (true) or the logical value 0% (false). BASIC!-PLUS stores 
the result in an integer variable, in one PDP—11 word of memory. For 
example: 

15 IF AX > BZ THEN GOTO 100 
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BASIC—PLUS performs two steps when it executes this statement: 

1. It compares the current values of A% and B% and stores the result 
(-1% or 0%) in an integer variable. 

2. It tests the value of this integer variable. If its value is 0%, 
BASIC-PLUS executes the next line in the program; if it is —1% (or any 
other nonzero value), BASIC—PLUS transfers control to line 100. 

You can program this operation as two separate steps. You can store a 
logical value in an integer variable at one point in a program and perform 
one or more logical tests on this stored integer at another point in the 
program. 

For example: 

20 XX = (AX > BX> 

4 

4 

4 

50 IF XX THEN GOTO 100 

When line 20 is executed, BASIC—PLUS evaluates A% > B% and stores the 
logical value -1% or 0% in the integer variable X%. When line 50 is exe¬ 
cuted, BASIC-PLUS tests the current value of X% to determine if it is true 
or false and proceeds accordingly. 

11.7.1.2 Logical Expressions 

BASIC—PLUS also evaluates as —1% or 0% a logical expression that com¬ 
pares two relational expressions. For example: 

20 IF (A > BX) ANO (CX < DX) THEN GOTO AOOO 

To evaluate this logical expression, BASIC—PLUS first evaluates each rela¬ 
tional expression. For each relational expression, BASIC-PLUS stores 
a logical value of either —1% or 0% in an integer variable. Next 
BASIC—PLUS compares the contents of these two integer variables based 
on the logical operator AND. The result of the AND operation is a single 
logical value of either -1% (true) or 0% (false). BASIC—PLUS uses this 
logical value to determine whether to execute line 4000. 

You can store the result of a logical expression in one statement and test it 
in another statement: 

20 XX ■= (AX < BX) AND (CX > DX) 


50 IF XX THEN GOTO 5000 

As before, BASIC—PLUS interprets 0% as false and —1% or any other non¬ 
zero value as true. 
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11.7.2 Other Logical Values 


Logical values are not restricted to 0% or —1%; every integer value is a 
logical value. Thus, you can store any integer value in a variable and test it 
at a later time. 

For example: 

20 XX = 5X 


4 

50 IF XX THEN GOTO 1000 

Since 5% is interpreted as true, control goes to line 1000. Line 20 can also 
contain an integer expression. For example: 

20 XX = (AX + BX)/ 2X 

You can use any expression or function that yields an integer value in an 
IF—THEN statement. For example; 

30 IF LEN(TYPED.RESPONSE*) THEN GO TO 2000 

This statement, which contains the string function LEN, transfers 
control to line 2000 if there are characters in the string variable 
TYPED.RESPONSE$. If TYPED.RESPONSE$ contains no characters, 
BASIC-PLUS executes the next line in the program. 

11.7.3 How BASIC-PLUS Performs Logical Operations 

Up to now, you have used logical values to mean true or false. But logical 
values have another use in BASIC-PLUS programming. You can use the 
logical operators to examine, set, and clear individual bits inside PDP-11 
16—bit words. To see how to use logical operators for this purpose, you need 
to know more about how BASIC-PLUS performs logical operations. 

The BASIC-PLUS logical operators (AND, OR, NOT, XOR, IMP, and EQV) 
act on entire 16—bit PDP—11 words. A logical operation is the result of 16 
single-bit logical operations. 

BASIC—PLUS performs a logical operation by comparing the bit patterns of 
two integers, one bit at a time. The type of comparison that BASIC-PLUS 
makes for each pair of bits depends on the logical operator that you specify. 

The truth tables in Table 11—1 show, for each logical operator, how 
BASIC!—PLUS compares bit pairs in two integers. 

For each operator in this table, A is a bit in one integer value, and B is the 
bit that occupies the same position (the "matching” bit) in the other integer 
value. The result of the logical comparison, shown on a third line, is stored 
in a third integer value. The NOT operator, unlike the rest, has only one 
operand. 


11-8 
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Table 11-1: Truth Values for Logical Operations 


AND 


A 

B 

110 0 

10 10 

AANDB 

10 0 0 


XOR 

A 

110 0 

B 

10 10 

AXORB 

0 110 


IMP 

A 

110 0 

B 

10 10 

AIMPB 

10 11 


OR 


A 

B 

110 0 

10 10 

A ORB 

1110 


EQV 

A 

110 0 

B 

10 10 

AEQVB 

10 0 1 


NOT 

A 1 

1 0 

NOT A 1 

0 1 


The following examples show how BASIC-PLUS produces logical values. 
Each example compares the integers 85% and 28% using a different logical 
operator. 

The first example prints the logical product of two integers, 85% and 28%, 
in immediate mode. (A logical product is the result of an AND operation.) 
An AND operation yields a 1 only when matching bits are both 1 and clears 
bits that are not set in both values. You can use an AND operation to see if 
two values have any set bits in common, to test specific bits, or to "mask” 
certain bits (see Section 11.7.4.3). 

PRINT 85:S AND 2QX 
20 

Ready 


To find the logical product of 85% and 28%, BASIC-PLUS performs 16 
AND operations, one on each pair of matching bits in the integers 85% and 
28%. BASIC—PLUS stores the result of these 16 AND operations in a third 
integer value. The following diagram shows the bit pattern of 85%, 28%, 
and the result. 


BIT 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 
85% == 0000000001010101 
28% » 000000000001 1100 


85% AND 28% = 0000000000010100 
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The bit pattern in the result is the integer value 20% (16% + 4%). This 
result occurs because the 16% bit and the 4% bit are set in both values 
being compared. 

The second example prints the logical sum of 85% and 28%. (The logical 
sum is the result of an OR operation.) Because an OR operation yields a 1 if 
either or both bits in a position are 1, you can use the OR operator to set 
specific bits in a word. 

PRINT 852 OR 282 
93 

Ready 


To find the logical sum of 85% and 28%, BASIC-PLUS performs 16 OR 
operations, one on each pair of matching bits in 85% and 28%. The follow¬ 
ing diagram shows this operation: 

BIT 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

85% = 0000000001010101 

28% = 0000000000011100 

85% OR 28% = 0000000001011101 

The logical sum of 85% and 28% is 93% (64% + 16% + 8% + 4% + 1%). 
The OR operator sets a bit if one or both bits being compared are set. 

The third example prints the logical difference of 85% and 28%. (The logical 
difference is the result of an XOR operation.) An XOR operation yields a 1 
only if either bit in a matching pair is set; otherwise it yields a 0. You can 
use XOR to toggle specific bits in a word. ("Toggling” a bit means setting a 
0 bit to 1 or a 1 bit to 0.) 

PRINT 852 XOR 282 
73 

Ready 


To find the logical difference, BASICJ-PLUS performs 16 XOR operations. 
The following diagram shows the result: 

BIT 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

85% = 0000000001010101 

28% = 0000000000011 100 

85% XOR 28% = 000000000100 1. 001 

The logical difference of 85% and 28% is 73% (64% -I- 8% + 1%). 
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11.7.4 Programming Applications 

Each bit in a PDP-11 word can store a piece of information. A set (1) bit 
can indicate the presence of a condition; a clear (0) bit can indicate the 
absence of a condition. Thus, a single word in memory can store up to 16 
pieces of information. 

Both BASIC—PLUS and RSTS/E take advantage of this compact form of 
information storage. For example, when you open a device with the OPEN 
statement, BASIC-PLUS places several pieces of information about the 
device in the special variable STATUS. By testing bits in the STATUS 
variable, you can get information about the device you just opened. (Section 

17.1.1 describes the STATUS variable and shows you how to test the bits.) 

SYS system function calls let you communicate with the RSTS/E monitor. 
In some calls, the monitor returns information to your program in string 
form. Certain bytes in the string contain several "bits” of information. To 
read this information, you can convert the string to an integer and then use 
logical operations to perform bit tests. (The RSTS/E Programming Manual 
describes how to perform the conversion and test the bits.) 

You can also use this technique in your own programs. You can use an 
integer variable to store several pieces of information. Then, at various 
points in a program, you can perform logical operations on that variable to 
test, set, and clear specific bits. 

The rest of this section shows some ways to use logical operations. 

11.7.4.1 Bit Tests 

The AND operator performs a bit test. You can use AND on an integer 
variable and a power of 2 to see if a specific bit is on in a word. For example: 

20 IF AX AND 8X THEN PRINT "Bit 3 is set" & 

ELSE PRINT "Bit 3 is clear" 

This is the technique you use to test bits in the STATUS variable and 
in "flag words” of data returned by certain SYS calls. (See the RSTS/E 
Programming Manual.) 

11.7.4.2 Setting or Clearing Bits 

The following statements set and clear bit 7 in the integer variable 
FLAG%: 


250 

FLAGI » FLAGX 

OR 

1287. 

! Tu rn 

on 

bit 

7 

260 

FLAG! « FLAGX 

XQR 

1287 

! Tu rn 

i t 

off 

if it is on 9 





I Tu rn 

i t 

on 

if it is off 

270 

FLAGZ = FLAGX 

AND 

(NOT 1287) 

1 Tu rn 

i t 

off 

unconditionally 


Integer and Floating-Point Operations 11-11 







11.7.4.3 Bit Masks 


Sometimes you may be interested in some but not all of the information 
stored in a word of memory. You can use an AND operation to hide or 
"mask” part of a bit pattern so you can access the part you are interested in. 
For example: 

30 LZ s MZ AND 255Z 

This statement mtisks out the high order bits (8—15) of W%. The value 
255% contains Is in bits 0 through 7 and Os in bits 8 through 15. Because 
an AND operation yields a 1 only if both bits are 1, the integer L% contains 
Os in bits 8 through 15 and the same bit pattern as W% in bits 0 through 7. 
The following diagram shows this operation (W% is an arbitrary bit 
pattern): 

BIT 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 

W%= 0100110101010101 

255% = 0000000111111111 

W% AND 255% = 0000000001010101 

(stored in L%) 


The result shows that L% has the same bit pattern as W% in the low order 
bits and all Os in the high order bits. The value 255% is a "bit mask” to hide 
the high order bits of a word. 

One application of bit masking is reading data returned by the file name 
string scan SYS call, which is described in the RSTS/E Programming 
Manual. For example, the monitor returns the project-programmer number 
of the file in one word, as shown: 


BIT 


15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 


Project Number 


Programmer Number 


HIGH BYTE 


LOW BYTE 


The data comes back in string form, so you must first convert the string 
data to integer data. (You can do this with the CVT$% function; see Section 
17.5.1.) Assume that you do the conversion and you store the contents of 
this word in the integer variable PPN%. You can then read either half of 
the word by using 255% as a bit mask. For example: 

PROGRAMMERZ = PPNZ AND 255Z 
PROJECTZ = SWAPZ(PPNZ) AND 255Z 

The SWAP% fimction swaps the two b 3 rtes in the word. Using SWAP% to 
put the project number in the low b 5 rte lets you read the project number 
using the same bit mask you used for the programmer number. See Section 
17.5.2 for information on the SWAP% function. For information on using 
system function calls, see the RSTS IE Programming Manual. 
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Here is another example of bit masking: 

PRINT CHR*(ASCI I("a") AND (NOT (32Z)) 

A 

Ready 

The ASCII value of a lowercase letter and its uppercase form differ by 32. A 
lowercase value has bit 5 on; an uppercase value has bit 6 off. Except for 
this bit, an uppercase letter and a lowercase letter have the same value. 

You convert a letter from its lowercase form to its uppercase form by clear¬ 
ing bit 5. The value NOT 32% is a "mask” to clear bit 5 because the value 
NOT 32% has all bits on except bit 6. 

The CVT$$ function performs this operation as part of its function that 
converts letters to uppercase. 

11.8 Floating-Point Arithmetic 

Floating-point numbers occupy either two or four 16—bit words of storage in 
memory. BASIC-PLUS uses two words with the single-precision math 
package and four words with the double-precision math package. Section 
F.4 describes the internal format of the two math packages. 

With the two-word format, you can accurately represent numbers up to six 
decimal digits. The four-word format lets you represent niunbers up to 15 
decimal digits. Both formats allow numbers in the range 10^-38 to 10^38, 
approximately. An attempt to assign or compute a number outside the 
allowed range causes the ”%Floating'point error” (ERR = 48). 

BASIC—PLUS prints numeric results of floating-point calculations in deci¬ 
mal or exponential format, as described in Section 8.3. To print numbers 
larger than six digits, you can tailor the format with the PRINT-USING 
statement (see Section 15.3.2). 

Usually you cannot represent fractional numbers exactly in binary nota¬ 
tion. Also, certain calculations in floating-point result in an accumulated 
error. The following calculation, run in standard four-word floating-point, 
results in an accumulated error. The error results because the floating¬ 
point fraction .01 cannot be represented internally as that precise value. 

LISTNH 

100 X = 0. 

110 X = X + .01 FOR IX = IX TO lOOOOX 
120 PRINT NUH1*(X-100.> 

327B7 END 

Ready 

RUNNH 

-.00000000000177635883940025 

Ready 
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If no accumulated error exists, the result is 0. Running the example on a 
system using the two-word format generates a much greater accumulated 
error (approximately .00295). 

NOTE 

The scaled arithmetic feature, available only on systems with 
the double-precision math package, lets you avoid or reduce 
accumulated error. Section 11.10 describes scaled arithmetic. 

11.9 Mixed Mode Arithmetic 

You can perform arithmetic operations using a mix of integer and floating¬ 
point numbers. To force a floating-point representation of an integer con¬ 
stant, end it with a decimal point. To force an integer representation of a 
constant, end it with the % character. Constants without a decimal point or 
% character are termed ambiguous. The rest of this section describes the 
results of arithmetic operations using a mixture of integer and floating¬ 
point numbers. 

If both operands of an arithmetic operation are explicitly either integer or 
floating-point, BASIC—PLUS generates integer or floating-point results, 
respectively. If one operand of an arithmetic operation is an integer and 
another is floating-point, BASIC-PLUS converts the integer to a floating¬ 
point representation and generates a floating-point result. For example: 

PRINT iX/21i 1./2.; lX/2.i i./2X 
0 ,5 < S <5 

Ready 

In the first two operations, BASIC—PLUS generates the explicit results; in 
the second two, BASIC—PLUS converts the explicit integer and generates 
floating-point results. 

Sometimes an ambiguous constant appears in an arithmetic expression (for 
example, 10 as opposed to 10% or 10.). If an integer variable or constant 
occurs an 3 rwhere to the left of the ambiguous constant, BASIC—PLUS 
represents it in integer format. Otherwise, BASIC—PLUS treats the ambig¬ 
uous constant as a floating-point number. For example: 

PRINT IX/ 2 ; 1/2T.; 1/2 

0 .5 .5 

Ready 


In the first operation, BASIC—PLUS treats the "2” as an integer. It does so 
because an explicit integer representation appears to the left in the expres¬ 
sion. In the next two operations BASIC-PLUS treats the ambiguous 
constants as floating-point numbers. It does so because no explicit integer 
variable or constant appears to the left of the ambiguous constant in the 
expression. 
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Because formatting determines the results of many operations, you should 
explicitly impose the correct format with the percent sign or the decimal 
point. Compare the following calculations, assuming A%(2%) = 0 in each 
expression: 

PRINT AT<2Z) + <32767+2)5 A7(Z7> + (32767.+2) 

-32767 32769 

Ready 

The percent sign in the first expression forces an integer result. The deci¬ 
mal point in the second expression forces a floating-point result. The same 
principle applies in the following example: 

PRINT n ♦ 1/2 5 1 . 1/2 5 1 + 1/2 

1 1.5 1.5 

Ready 

Use of an explicit percent sign or decimal point lets you control the result in 
mixed-mode operations. 

11.10 Scaled Arithmetic 

On a system with the double-precision floating-point (four-word) math 
package, the scaled-arithmetic feature lets you avoid or reduce accumu¬ 
lated error in the fractional part of a nxunber. Systems with two-word preci¬ 
sion do not have scaled arithmetic. To work with the scaled arithmetic 
feature, you use the SCALE command to specify a scale factor. 

NOTE 

The optional string arithmetic feature provides another 
alternative to scaled arithmetic for providing better precision 
in non-integer arithmetic. Unlike scaled arithmetic, which is 
limited to a scale factor between 1 and 6, string arithmetic 
has many digits of accuracy. However, string arithmetic 
achieves higher precision at the cost of slower calculation 
speed. 

11.10.1 The Scale Factor 

You can select a scale factor of 0 to 6. BASIC-PLUS uses the scale factor to 
preserve the accuracy of fractional numbers to that number of decimal 
places. The value 0, which is the default scale factor, is a special scale factor 
that disables the scaled-arithmetic feature. When the scale factor is 0, 
BASIC—PLUS performs calculations using standard double-precision 
floating-point arithmetic. (Note that your system manager can change the 
default scale factor to a nonzero value.) 
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The scale factor is set to its default value when you enter BASIC-PLUS. 
Each time you reenter BASIC-PLUS, the scale factor is reset to its default 
value. For example, you reenter BASIC-PLUS after executing system pro¬ 
grams, such as PIP, that are not compiled with the same nm-time system 
you are in. 

BASIC-PLUS uses the scale factor when it translates a program. The scale 
factor in effect during translation determines how floating-point calcula¬ 
tions will be performed when the program is executed. Suppose you specify 
a scale factor of 2 and then use OLD to retrieve a program. BASIC-PLUS 
translates the program using a scale factor of 2. Now you run the program 
and input a floating-point number. BASIC-PLUS internally moves the 
decimal point 2 places to the right and truncates it to an integer. 
BASIC-PLUS performs all subsequent calculations with the floating-point 
integers. Next, BASIC—PLUS translates the result of each arithmetic oper¬ 
ation into a floating-point integer with the scale factor 2. On output, 
BASIC-PLUS moves the decimal point to the left 2 places (descales) and 
passes the result to the PRINT or PRINT-USING routines to format. 

For example, with a scale factor of 2 in effect, the following statement 
causes BASIC-PLUS to move the decimal point two places to the right: 

X = .01 

If any rounding is necessary, it is done at this point. BASIC—PLUS converts 
the result, 1, to a floating-point representation. Similarly, .1 becomes 10 
internally and all numbers less than .005 become 0. 

The scaled arithmetic conversion thtis avoids the loss of precision inherent 
in representing fractional numbers in binary notation. BASIC—PLUS can 
represent the integer accurately in floating-point format. This feature, 
therefore, allows more predictable arithmetic results. For example, running 
the following calculation without a scale factor yields a result of 
—.177636E-11. But nmning the same calculation with a scale factor 5 rields 
a result of 0: 

SCALE 2 
Ready 

100 X = 0. 

110 X = x+.oi FOR IZ = IZ TO lOOOOZ 
120 PRINT X-100 
32767 END 
RUNNH 
0 

Ready 


The scale factor of 2 eliminates the inaccuracy in representing a fraction 
two places to the right of the decimal point. 
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The range of integer numbers that can be accurately represented decreases 
according to the scale factor in effect. For example, with a scale factor of 2 
in effect, two of the 15 digits represent the two digits of fraction. Thirteen 
places are left to accurately represent the integer portion of the number. 

With a scale factor in effect, BASIC-PLUS handles output by PRINT and 
PRINT-USING statements in the standard manner. The PRINT statement 
still handles six digits or less, using the E format for numbers larger t^ban 
six digits. The PRINT—USING statement formats numbers according to the 
specified string. 

You can use the mathematical functions described in Section 9.8 in con¬ 
junction with the scaled-arithmetic feature. With a nonzero scale factor in 
effect, BASIC—PLUS automatically: 

1. Descales the number passed 

2. Computes the value of the function 

3. Converts the value returned to an appropriately scaled floating-point 
integer 

No rounding occurs; places outside the scale factor range are truncated. 

11.10.2 The SCALE Command 

The SCALE command lets you control the scale factor. SCALE is a 
BASIC—PLUS command; it cannot be used as a program statement. 

BASIC—PLUS establishes the scale factor for a program during translation, 
not during execution. Translation occurs when you use the NEW or OLD 
command, and when you run a program from its source (.BAS) file. Thus, if 
you want to set the scale factor for a program, use the SCALE command 
before NEW, OLD, or RUN. 

BASIC—PLUS keeps track of two scale factors: the current scale factor, used 
when your current program was translated, and the pending scale factor, to 
be used the next time translation occurs. The scale factor has a default 
value of 0, which means that BASIC-PLUS uses no scale factor when 
translating the program. On systems with the single-precision math pack¬ 
age, the scale factor is always 0. The system manager can change the scale 
factor’s default value on systems with the double-precision math package. 

The SCALE command has two functions: it displays the two scale factors 
and lets you set a new pending scale factor. 

The SCALE command has the format: 

SCALE [n] 

where n is an integer between 0 and 6. 
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The following examples show how the SCALE command works: 

SCALE Displays the current scale factor and the pending scale factor. For 
example: 

SCALE 
6 >2 

This display means that your current program was translated using a 
scale factor of 2; the next time translation occurs, the scale factor will 
be 6. One value is printed if both scale factors are the same. 

SCALE 2 Sets the scale factor to 2; this value is used the next time translation 
occurs. On systems with the single-precision math package, the mes¬ 
sage ''?Missing special feature” is printed when you try to set the scale 
factor. 

SCALE 0 Disables the scaled arithmetic feature. BASIC-PLUS uses no scale fac¬ 
tor when translating a program. 


Examples 

SCALE 2 
Ready 
NEW TEST 
Ready 

10 PRINT .01 ..025..003 

20 END 

RUNNH 

.01 .02 0 

Ready 

10 PRINT 1000.00*.075 
RUNNH 
70 

Usage Notes 

1. Remember that BASIC—PLUS establishes the scale factor for a pro¬ 
gram during translation, not during execution. To change the scale 
factor for a program, always issue the SCALE command just before 
translation occurs, that is, before you use the NEW or OLD command, 
or before you run a program from its source (.BAS) file. 

2. When you run a program, the scale factor used in computations is 
always the scale factor that was in effect when the program was 
translated. 

3. If you set a new pending scale factor while yop have a program in 
memory that was translated using a different scale factor, and then you 
run the program in memory, BASIC—PLUS displays the warning mes¬ 
sage "%Scale factor interlock.” This message reminds you that the scale 


11-18 


Integer and Floating-Point Operations 





factor you set has not yet taken effect. The program runs, but numeric 
results are computed using the scale factor in effect when the program 
was translated. (The new scale factor takes effect when you use NEW or 
OLD, or run a program from its source file.) 

4. If you set a new pending scale factor and then run a .BAG file that was 
translated using a different scale factor, BASIC-PLUS again computes 
results using the scale factor in effect when the .BAG file was trans¬ 
lated. In this case, BASIC-PLUS does not display the "%Scale factor 
interlock” message. 

5. When you run a .BAG file, BASIC-PLUS changes the current scale 
factor to the scale factor in effect when the .BAG file was translated. 
The pending scale factor does not change. 

For example, suppose that the current scale factor is 2 and the pending 
scale factor is 6: 

SCALE 

6 »2 

You run a .BAG file that was translated using a scale factor of 0: 

RUN ZERO.BAG 

If you again display the current and pending scale factors, you see that 
the current scale factor is now 0 but the pending scale factor is still 6: 

SCALE 

6 .0 

6. Immediate mode statements are always translated using the current 
scale factor. If you set a new pending scale factor and then enter an 
immediate mode statement: 

• The scale factor you specify has no effect. 

• The ’'%Scale factor interlock” message is displayed on your terminal. 

7. The scale factor is reset to its default value whenever your user job 
changes run-time systems. This happens when you: 

• Run a RSTS/E system program such as PIP or QUE, using RUN or a 
GGL command 

• Use a DGL command 

• Ghange your job keyboard monitor with SWITGH 

• Use another language compiler such as BASIG-PLUS-2 or GOBOL 
The scale factor is also reset to its default value when you log out. 
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Chapter 12 
Matrix Manipulation 


This chapter describes the BASIC-PLUS matrix manipulation statements. 
These statements, called MAT statements, operate on entire matrices. 
MAT statements are an optional BASIC-PLUS featiire, so they may not be 
available on your system. 

Matrices (also called arrays) can be composed of variables of any type. A 
single matrix, however, is composed of a single type of data: floating-point, 
integer, or string. Note that the MAT operations in this chapter do not use 
the zero elements [A(0), or B(0,n) and B(n,0)] of the specified matrix. 

12.1 Array Storage 

You can deflne the size of a matrix either explicitly or implicitly. To explic¬ 
itly define the size of a matrix, use the DIM statement. If you do not 
explicitly dimension the matrix with the DIM statement, BASIC—PLUS 
assumes the matrix has eleven elements in each dimension you reference. 
A one-dimensional matrix has eleven elements; a two-dimensional matrix 
has eleven rows and eleven columns. Each dimension includes a zero row 
and column, which are ignored by MAT statements. When you use matrices 
with fewer than eleven elements in each dimension, explicitly dimension 
them to conserve memory space. 

Implicitly dimensioning the matrix A(I,J) has the same effect as explicitly 
including the following statement: 

100 DIM A(lO.lO) 

Dimensioning a matrix establishes two quantities for BASIC—PLUS: the 
maximum number of elements in each row and column, and the maximum 
number of elements in the matrix. 
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You can change the number of elements in each row and the number of 
columns in the matrix with the MAT statements. However, the total num¬ 
ber of elements cannot exceed the number defined when the matrix was 
dimensioned. Changing the number of elements in either or both dimen¬ 
sions is called redimensioning the matrix. 

When you use a matrix, be careful not to reference elements outside its 
dimensioned range. If the range of matrix A is 5—by-7, for example, 
referencing A(3,8) is improper. 

Depending on which subscript is out of bounds (and by how much), either a 
"?Subscript out of range” error is generated or an unexpected element of 
the matrix will change. This result occiurs because BASIC-PLUS tracks 
only the total size of the array, not the bounds of each subscript. 

12.2 MAT READ Statement 

The MAT READ statement reads the value of each element of a matrix 
from DATA statements. The statement has the form: 

MAT READ <list of inatrices> 

Each element in the list of matrices indicates the maximum amount of the 
matrix to be read. This amovmt cannot be greater than the dimensioned 
size of the matrix. The individual elements are separated by commas. If you 
use the matrix name without a subscript, the entire matrix is read. For 
example: 

100 DIM AX(20»20) 

110 MAT READ AX 

The preceding lines read a 20-by-20 matrix of integer data. Data is read 
row by row; that is, the second subscript varies most rapidly. The following 
statement reads a 5—by—15 matrix and redimensions the matrix A% to be 
5—by—15: 

110 MAT READ AX<5 *15) 

12.3 MAT PRINT Statement 

The MAT PRINT statement prints each element of a one- or two- 
dimensional matrix, except elements in row 0 and column 0. The statement 
has the form: 

MAT PRINT <matrix naine> 

If the matrix name consists of an unsubscripted matrix name, 
BASIC-PLUS prints the entire matrix. If the matrix name is subscripted, 
then the subscript indicates the maximum size of the matrix to be printed. 
The matrix, however, is not redimensioned. Only one matrix can be output 
by a single MAT PRINT statement. 
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The semicolon and the comma determine the output format of the matrix. If 
the matrix name is followed by a semicolon (;), BASIC-PLUS prints out 
data values in a packed fashion. If a comma follows the matrix, the data 
values are printed across the line, one value per print zone. If neither 
character follows the matrix name, each element is printed on a separate 
line. Note the difference between matrix A; and matrix B(4,6), in the fol¬ 
lowing example: 

100 DIM A<10.10) *6(20*20> 

no MAT PRINT a; &. 

!PRINT lO-BY-10 MATRIX. PACKED FORMAT 
120 MAT PRINT B(4 .6) . & 

!PRINT 4-BY-B MATRIX. 5 ELEMENTS PER LINE 

Line 110 prints out a 10—by—10 matrix, with no extra spaces between 
elements. Line 120 prints a 4—by—6 matrix with wider spacing between 
elements. 

BASIC—PLUS can print one-dimensional arrays in either row or column 
format. In the following examples, V is a one-dimensional array. This state¬ 
ment prints the array V as a column matrix: 

220 MAT PRINT 0 

This statement prints the array V as a row matrix, five values per line: 

220 MAT PRINT V. 


This statement prints the array V as a row matrix, closely packed: 

220 MAT PRINT V! 


For example: 


LISTNH 

100 DIM A<7) . X(5) 

110 MAT READ A.X 

120 MAT PRINT A; & 

\ PRINT 8. 

\ MAT PRINT X 

200 DATA 21 .22.23.24 .35 .36 .37.51 .52 .53 .54 .55 
32767 END 


Ready 


RUNNH 

21 22 23 24 35 36 37 

51 

52 

53 

54 

55 

Ready 
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Two-dimensional arrays are printed in ascending (row by row) sequence. 
This means that the second subscript varies most rapidly. For example: 


LISTNH 

100 DIM A(2>3) ^ 

110 FDR IZ = IX TO 2X & 

\ FOR JX = IX TO 3X & 

\ LET A(IX#JX) = IX*100X + JX fit 
\ NEXT JX 8c 
\ NEXT IX 8e 
\ PRINT 

120 MAT PRINT A5 
32767 END 

Ready 

RUNNH 

101 102 103 
201 202 203 


Ready 


12.4 MAT INPUT Statement 

You can use the MAT INPUT statement to input the value of each element 
of a matrix. The statement has the form: 

MAT INPUT <list of matrices> 

BASIC-PLUS reads input from the keyboard, as with a normal INPUT 
statement, and prints a ? character when ready to accept the input. You can 
use the LINE FEED key to continue typing data on successive lines. Use 
the RETURN or ESCAPE key to enter the data into the system. MAT 
INPUT does not affect row 0 or column 0 of the matrix. 

The MAT INPUT statement allows input of integer, floating-point, or 
string values, depending on the variable names. When more than one 
matrix is to be input by the same MAT INPUT statement, separate the 
names by commas. For example: 

100 DIM AX(20)? B(15) 

110 MAT INPUT AX* B 

These statements cause the program to input 20 integer elements for the 
array A% and 15 floating-point values for the array B. 

Only 25 elements of the array are input in the following example, where an 
array or matrix element is specified: 

200 MAT INPUT NX(25) 
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This result occurs regardless of the number of elements originally specified 
when the array was dimensioned. The array is then redimensioned. For 
example: 


LISTNH 

100 DIM A(20.20) 

110 MAT INPUT A<4>3> 

120 PRINT t. 

\ MAT PRINT Af 
32767 END 


Ready 

RUNNH 

? 5.8f4.5.2.0*l»9.2*0.B.8i2.7*3.01 #8.345 


5 

8 

4*5 

2 

0 

1 

9«2 

0 

648 

2.1 

g^oi 

64345 

Ready 




The matrix A is redimensioned in line 110. The INPUT statement accepts 
input until the entire matrix has been read or until it encounters the 
RETURN or ESCAPE delimiter. You can input several lines by ending the 
terminal line with a LINE FEED to indicate continuation on the following 
line. 

Following the input of a matrix, the two variables NUM and NUM2 con¬ 
tain the number of elements input. NUM contains the number of rows 
input or, for a one-dimensional matrix, the number of elements entered. 
NUM2 contains the number of elements in the last row. The following 
sample program inputs a variable size matrix (up to lO-by-10): 


LISTNH 

100 DIM A(10 #10) 

110 INPUT 'TYPE MATRIX DIMENSIONS UP TO 10#10'!N#M & 

\ MAT INPUT A<N#M) 

120 PRINT 'NUM ='5NUM» 'NUM2 =';NUM2 

130 IF NUM»NUM2=N«M THEN PRINT 'MATRIX FILLED' & 

\ GO TO 32767 

140 PRINT 'MATRIX NOT FILLED' 

32767 END 


Ready 

RUNNH 

TYPE MATRIX DIMENSIONS UP TO 10*10? 4*8 

? 123 *456 *345 *909 *7B5 *45G *123 *1 *2 *3 *4 *5 *6 *7 *8 *9 *0 *0 *9 *8 *7 *45 
NUM = 3 NUM2 » B 
MATRIX NOT FILLED 


Ready 
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The following statement checks the contents of the matrix: 

MAT PRINT a; 

123 456 345 909 765 456 123 1 
23456789 
00 9 9 7 45 0 0 

00000000 

Unlike the INPUT statement, the MAT INPUT statement does not permit 
the output of a text string. For example: 

100 MAT INPUT 'CONTENTS OF MATRIX'5AZ 
?Syntax error at line 100 


Ready 

12.5 Matrix Initialization Statements 

A matrix initialization statement lets you create initial values for the ele¬ 
ments of a matrix. You can also use a matrix initialization statement to 
redimension an array. The statement has the form: 


MAT <matrix name> 


ZER 

CON 

IDN 


[(dimension(s))] 


where: 


<matrix name> Is the name of a predimensioned matrix. 

ZER Sets elements of the matrix to 0. (BASIC—PLUS sets all 

matrix elements to 0 when it creates a matrix.) 

CON Sets elements of the matrix to 1. 

IDN Sets an identity matrix; all elements are 0 except those 

on the diagonal, A(I,I), which are 1. 

ZER, CON and IDN do not affect row 0 or column 0 of the matrix. 

The optional dimensions indicate the size of the matrix. When specified, 
they cause the matrix to be redimensioned. When you do not specify dimen¬ 
sions, the existing dimensions of the matrix are assumed to be unchanged. 

The following example shows the use of matrix initialization statements: 

LISTNH 

100 DIM A<10»10)» B(15). C(20»20) 

110 MAT A=ZER & 

ISETS ALL ELEMENTS OF A EQUAL TO 0 
120 MAT B = C0N(10) 8. 

•SETS FIRST 10 ELEMENTS OF B EQUAL TO 1 
130 MAT C=IDN(10»10) & 

•SETS UP AN IDENTITY MATRIX 
32767 END 

Ready 
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RUNNH 


Ready 

MAT PRINT C; 

1 0 0 0 0 

0 10 0 0 
0 0 10 0 
0 0 0 1 0 

0 0 0 0 1 

0 0 0 0 0 

0 0 0 0 0 

0 0 0 0 0 

0 0 0 0 0 

0 0 0 0 0 

Ready 


0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
0 0 0 0 0 
1 0 0 0 0 
0 10 0 0 
0 0 10 0 
0 0 0 1 0 
0 0 0 0 1 


12.6 Matrix Calculations 


You can use matrices with mathematical operators and two intrinsic 
functions. 

12.6.1 Matrix Operations 

You can perform addition and subtraction on matrices with the common 
mathematical s)anbols. The following program uses both addition and sub¬ 
traction of matrices: 


LISTNH 



100 

DIM A<3)t 

B(3)# C(3) 

no 

A(I)=I FOR 

I«n TO 3* 

120 

B(I)=I#2« 

FOR 1=1* TO 

130 

MAT C«A+B 


140 

MAT PRINT 

C5 

150 

MAT C=B-A 


160 

MAT PRINT 

Cf 

170 

END 


Ready 



RUNNH 




3 6 9 

1 2 3 

Ready 


!ELEMENTS OF A ARE 1#2»3 
3, 'ELEMENTS OF B ARE 2ta pG 
!l+2» 2+A# 3+6 

!2-l # 4-2 t 6-3 
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You can perform addition and subtraction only on matrices that are the 
same size. The following example shows that you cannot indicate a subset 
of one matrix as part of an operation: 

no DIM A<50)f B(25>» C<50) 

120 MAT C=A+B 

RUNNH 

? MatriK diMension error at line 120 

For line 120 to execute properly, line 110 should read: 

no DIM A(50)» BOO) * C<50) 

There are two kinds of multiplication for matrices: scalar multiplication 
and multiplication of conforming matrices. You can multiply conforming 
matrices as follows: 

100 DIM D(10.5>. C(5.10). R<10.10) 

no MAT R = D»C 

D, C, and R in line 110 are conforming matrices because the number of 
columns in matrix D equals the number of rows in matrix C. The dimen¬ 
sions of the matrix R must be large enough to contain the number of col¬ 
umns in D and the number of rows in C. 

You can perform scalar multiplication of a matrix as follows: 

150 MAT C = <K)*A 

Each element of matrix A is multiplied by the scalar value (constant, varia¬ 
ble, or expression) K, indicated in parentheses. The form MAT A = (K)*A is 
also legal. 

Matrix A can be copied into matrix C (providing enough space is available 
in matrix C) as follows: 

160 MAT C = A 

12.6.2 Matrix Functions 

Three functions allow transposition and inversion of matrices: 

TRN - Transposes the matrix 
INV - Inverts the matrix 

DET - Returns the value of the determinant of the matrix after inversion 

The following statement causes matrix C to be set equal to the transposi¬ 
tion of matrix A: 

150 MAT C = TRN(A) 
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That is, C(I,J) = A(J,I) for all I,J; matrix C is redimensioned if necessary. 
For example: 

10 DIM X<15t25)f N(5fl0)t M(5#5> 

90 MAT N=IN0(M) 

100 PRINT '‘DETERMINANT OF MATRIX M IS” 5 DET 


This causes N to be computed as the inverse of matrix M (M must be a 
square matrix). After the inversion is complete, the function DET is set to 
the value of the determinant of matrix M. (If the matrix being inverted is 
singular, and thus cannot be inverted, the message '7Can't invert matrix” 
is printed.) You can use the value of DET in subsequent computations, as 
you use any other function. For example: 


LISTNH 

200 MAT A = INO(X) & 

\D1=DET 

210 MAT B = INO(A) & 

\D2=DET 

220 IF Dl=l/D2 GO TO 340 ELSE PRINT 'RELATIONSHIP TRUE' 
Ready 


Matrix inversion, like the other BASIC-PLUS matrix operations, does not 
operate on the elements of the row 0 and column 0 of the matrix. Inversion, 
however, destroys the previous contents of these elements. The operation 
MAT A = INV(A) is legal. 
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Chapter 13 

Advanced Statements and Features 


This chapter describes advanced BASIC—PLUS statements and features. 
Several statements in this chapter are more advanced forms of statements 
described in Chapter 9. 

This chapter describes the following topics: 

Topic Statements or Functions 


Multiple Line Function Definitions 
Conditional Transfer of Control 
Conditional Termination of FOR Loops 
Statement Modifiers 
Error Handling 
System Functions 
Suspending Program Execution 
Transferring Control Between Programs 


DEF* 

ON-GOTO, ON-GOSUB, IF-THEN-ELSE 

FOI^-WHILE, FOR^UNTIL 

IF, UNLESS, FOR, WHILE, UNTIL 

ON ERROR GOTO, RESUME 

DATE$, TIME$, TIME 

SLEEP, WATT 

CHAIN 


13.1 DEF* Statement, Multiple>Line Function Definitions 

The DEF* statement, described in Section 9.9, shows how to create a one- 
line function that you can use as an element in a BASIC-PLUS statement. 
You can also use DEF* to define multiple-line functions. The format for a 
multiple-line function definition is: 

DEF* FN<variable(arguments)> 

<body of definition> 

FNEND 
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As in the single-line DEF* function, the arguments can be zero to five 
dummy variables of any type or mixture of types. However, unlike the 
single-line DEF* function, the multiple-line DEF* function has no equal 
sign after the function name on the first line. 

Within the multiple-line definition, you should have a statement of the 
form: 

[LET] FN<variable> = <expre8sion> 

The DEF* function returns the value of FN<variable> when it reaches the 
FNEND statement. 

The value of this expression is returned as the value of the function. There 
can be more than one such statement. The following example returns the 
larger of the two nvunbers: 

100 DEF* FNM(X»Y) 

no LET FNM = X 

120 IF X<=Y THEN GOTO 140 

130 LET FNM=Y 

140 FNEND 


The next example shows a recursive function that computes N-factorial. 
The term "recursive” refers to the repetitive process where the result of 
each cycle depends on the result of the previous cycle. 


LISTNH 

100 DEF* FNF(M*) 

105 IF MX = OX THEN FNF = 1 & 

\ GO TO 120 

no IF MX = IX THEN FNF » 1 8. 

ELSE FNF = MX * FNF(MX-IX) 

120 FNEND 

130 INPUT 'VALUE FOR FACTORIAL'! MX 

140 PRINT MX! 'FACTORIAL EQUALS'! FNF(MX) 

32767 END 

Ready 

RUNNH 

VALUE FOR FACTORIAL? B 
6 FACTORIAL EQUALS 720 


Ready 

RUNNH 

VALUE FOR FACTORIAL? 0 
0 FACTORIAL EQUALS 1 


Ready 


Any non-dximmy variable you reference in a function definition has the 
current value of that variable in your program. These variables retain any 
value you assign during execution. Also note that not all context informa¬ 
tion is saved in functions. Fimction parameters are saved and restored, but 
variables and information stored in temporary locations are not saved. 
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You can nest multiple-line DEF* function calls; that is, one multiple-line 
function can reference another. A multiple-line function lets you transfer 
control outside its boundaries with GOSUB, ON ERROR... RESUME, 
nested function references, or GOTO. However, you must follow certain 
rules when you transfer control out of a function or enter a function from 
outside its bovmdaries. For example, once a function is entered, it must be 
exited through its FNEND statement. Also note that an error occurs if 
BASIC—PLUS encounters an FNEND statement whose companion DEF* 
FN... statement has not been executed. You should avoid transfers out of 
function boundaries—^they may not execute as expected in other versions of 
BASIC. 

The parameters you use to call a user-defined function are formal. This 
means that their former values are retained after the function has been 
invoked. For exsimple: 

LISTNH 

100 DEF* FNB (X) 

no X=0 B. 

\FNB=10 
120 FNEND 
200 A^l & 

\B=FNB(A) & 

SPRINT A*B 
32767 END 

Ready 

RUNNH 

1 10 
Ready 


Note that A is not set to 0 by the function FNB(A). 

You can write functions using a variety of argument types. For example: 


LISTNH 

100 DEF* FNA«(A#B#CZ) 

110 IF A>B THEN FNA$ = CHR$(A+CT.) 8c 
ELSE FNA$ - CHR$(A+1) 

120 FNEND 

200 INPUT ^VALUES FOR A»BfCX'; AfB 

210 PRINT 'FNA$(A#BtCX) = ' 5FNA$(AfB) 

327B7 END 

Ready 

RUNNH 

OALUES FOR AtbtCX? 36>7.5#24 
FNA$(A#B#CX) * < 

Ready 

RUNNH 

VALUES FOR AtB#CX? 45.2#5*S7#8 
FNA$(A#B#CI) » 5 


Ready 
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13.2 ON-GOTO Statement 


The simple GOTO statement transfers control of the program to another 
line number. The ON-GOTO statement transfers control to one of several 
lines, depending on the value of an expression, when the statement is exe¬ 
cuted. The statement has the form: 

ON <expre8sion> GOTO <list of line numbers> 

BASIC-PLUS evaluates the expression, using the integer part as an index 
to one of the line nvimbers in the list. For example: 

50 ON X GOTO 100.200»300 

This statement transfers control to line munber: 

100 if X is greater than or equal to 1. and less than 2. 

200 if X is greater than or equal to 2. and less than 3. 

300 if X is greater than or equal to 3. and less than 4. 

Note that the preceding line 50 is equivalent to: 

50 IF X=1 THEN S. 

GOTO 100 & 

ELSE IF X = 2 THEN 8< 

GOTO 200 & 

ELSE IF X=3 THEN & 

GOTO 300 

However, the ON-GOTO statement in line 50 requires less storage space 
and executes faster. 

Values of X out of the range 1,2,3 in this example cause the error message: 
?0n statement out of ranee at line 50 

However, you can transfer to an ON ERROR GOTO routine, checking for 
ERR=58. (See Section 13.7.) 

13.3 ON-GOSUB Statement 

The GOSUB statement transfers control of your program to a subroutine; 
the RETURN statement returns control firom that subroutine to normal 
program execution (see Section 9.10 for details). The ON-GOSUB state¬ 
ment conditionally transfers control to one of several subroutines or to one 
of several entry points in one (or more) subroutine(s). (See ON-^GOTO con¬ 
ditions, Section 13.2.) The statement has the form: 

ON <expression> GOSUB <li8t of line number8> 
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The integer value of the expression determines which line number control 
transfers to. When the RETURN statement is executed, control transfers to 
the line following the ON-GOSUB line. 

Consider the following example: 

80 ON XZ-YX GOSUB 900*933>1014 

When line 80 is executed, the value of X%-Y% is calculated. If the value is 
1, control transfers to line 900; if the value is 2, control goes to line 933; if 
the value is 3, control goes to line 1014, If the quantity X%—Y% is not equal 
to 1, 2 or 3, the following error message is printed: 

?0n statement out of ranse at line 80 

You can transfer to an ON ERROR GOTO routine with ERR=58 (see 
Section 13.7). 

Since you can transfer into a subroutine at different points, you can use 
the ON-GOSUB statement to determine which portion of the subroutine 
should execute. 


13.4 IF-THEN-ELSE Statement 


The IF-THEN statement transfers control to another line or executes a 
specified statement, depending on a stated condition. 

The IF—THEN—ELSE statement is the same as the IF-THEN statement. 
But instead of executing the line that follows the IF statement, you can 
specify another line number or statement for execution when the condition 
is not met. The statement has the form: 


IF <condition> 


THEN <statement> 

THEN <line number> f ELSE <statement> 1 
GOTO <line number> IeLSE <line number> J 


The <condition> is either a relational expression or a logical expression. 

A relational expression is defined as: 

<expre8sion> <relational operator> <expre8sion> 

The relational expression is described in Section 8.4.3. 
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A logical expression is one of the following: 

1. An integer expression (FALSE if 0, TRUE if <>0) 

2. A set of relational expressions, connected by logical operators 

3. A set of integer expressions, logical expressions, or both, connected by 
logical operators 

The condition is tested; if it is true, the system executes the THEN or 
GOTO part of tiie statement. If the condition is false, the ELSE part of the 
statement is executed. 

Here is an example of an IF-THEN-ELSE statement: 


75 IF X>Y THEN PRINT "GREATER" ELSE PRINT "NOT GREATER" 


Another IF statement can follow either the THEN or ELSE clause in the 
preceding example. In this way, you can nest the IF statement to any level 
you want. Use line continuation and spaces or tabs to make these complex 
statements easier to read. For example: 


LISTNH 

100 INPUT 'ENTER THREE NUMBERS'»A»B»C 
110 IF A>B THEN & 

IF B>C THEN PRINT 'A>B>C' & 

ELSE IF OA & 

THEN PRINT 'C>A>B' & 
ELSE PRINT 'A>C>B' 8. 
ELSE IF A>C THEN PRINT 'B>A>C' & 

ELSE IF B>C & 

THEN PRINT 'B>C>A' 8. 
ELSE PRINT 'C>B>A' 

32767 END 


Ready 

RUNNH 

ENTER THREE NUMBERS? 4«6f-* 01 »-3.5 
A>B>C 


Ready 

RUNNH 

ENTER THREE NUMBERS? 2005>2.8»300S 
C>A>B 


The IF-THEN-ELSE statement can appear anywhere in a multi-statement 
line. However, if any other statements follow, all statements up to the next 
line number are part of the THEN or ELSE clause. For example: 


210 IF A=1.0 THEN GOTO 100 ELSE PRINT A\ PRINT 'ABNORMAL' 
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The value of A and the text string ABNORMAL are both printed when 
Aol. 


20 IF A>B THEN IF B<C THEN PRINT & 

\ GOTO 30 
25 PRINT''A<B" 

30 STOP 


The statement GOTO 30 is encountered and executed only when ”B<C” is 
printed. If either A<B or B>C, the line "A<B” is printed. 


13.5 Conditional Termination of FOR Loops 

In the simple FOR-NEXT loop described in Section 9.5.1, the format of the 
FOR statement is given as: 

FOR <variable> = <expre8sion> TO <expre88ion> [STEP <expre8sion> ] 

Often you do not know the final value of the loop variable, and you want to 
execute the loop many times to satisfy some condition. This condition might 
be the point where further iterations of a function contribute no accuracy to 
the result. BASIC-PLUS provides a convenient way of specifying that a 
loop is executed until a condition is detected or while some condition is 
true. These statements take the form: 


FOR <variable> = <expression> [STEP <expres8ion> ] | | 


The <condition> is either a relational expression or a logical expression. 
BASIC-PLUS evaluates the condition before the loop executes and also 
at each loop iteration. The iteration proceeds if the result is true 
(FOR-WHILE) or false (FOR-UNTIL). 

There is a notable difference between a FOR loop with WHILE or UNTIL 
and one with a terminal value for the loop variable. Consider the two loops 
in the following program: 


LISTNH 

10 FOR IX«1X TO lOX 8c 

\ PRINT 1X5 Sc 
\ NEXT IX 

20 PRINT 'IX=MIX 

50 FOR IX=IX UNTIL IX>10X & 

\ PRINT 1X5 8c 
\ NEXT IX 

60 PRINT 'IX='5IX 

32767 END 

Ready 

RUNNH 

1 2 3 4 5 B 7 8 9 10 IX= 10 
1 2 3 4 5 6 7 8 9 10 IXs: 11 


Ready 
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Each loop prints the numbers from 1 to 10. When the loop at line 10 is done, 
however, the loop variable is set to the last value used (that is, 10). In the 
second loop beginning at line 50, the loop variable is set to the value that 
caused the loop to be terminated (that is, 11). 

Now consider the next two loops: 


LISTNH 

10 

X=10 

20 

FOR 1=1 TO X & 

\ X = X/2 &C 
\ PRINT IfX & 

\ NEXT I 

30 

PRINT 8c 
\ X=10 

40 

FOR 1 = 1 UNTIL I>X 8c 
\ X = X/2 8c 
\ PRINT I fX 8: 

\ NEXT I 

32767 

Ready 

END 

RUNNH 

1 

5 

2 

2^5 

3 

1^25 


4 

5 

6 

7 

8 

9 

10 


♦ B25 

♦ 3125 

♦ 15625 
♦078125 
♦390825E-1 
♦195313E-1 
♦976563E-2 


1 

2 


5 

2^5 


Ready 


In the loop beginning with line 20, the iteration stops when I exceeds the 
initial value of X (that is, 10). Even though the value of X changes in the 
loop, the initial value of X determines the performance of the loop. 

In the second loop, the current value of X determines when the iteration 
ceases. Thus, after three iterations, I is greater than X in the second loop 
and the program ends. (When you omit the STEP value, it is assumed to 
be 1.) 

These forms of loop control are useful in iterative applications where data 
generated during the loop execution detennines loop completion. 

Consider the problem of scanning a table of values until two successive 
elements are both 0 or the end of the table is reached; 


100 FOR IZ=1Z UNTIL IZ=NZ OR X(IZ)=0 AND X(IZ+1Z)=0 
200 PRINT X(IZ) 

300 NEXT IZ 


13-8 
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The following two programs also illustrate the FORr-UNTIL and 
FORr-WHILE constructs: 

LISTNH 

100 INPUT 'LETTER IS'5 Y$ 

110 X$=" 

120 FOR IX-OX UNTIL X$=Y$ OR X$ = 'ZZZ' & 

\ READ X$ & 

\ NEXT IX 

130 IF X$ = 'ZZZ' THEN PRINT 'IMPROPER INPUT' & 

\ GO TO 32767 

140 PRINT 'LETTER IS NUMBER';iX; 'IN ALPHABET' 

500 DATA A»B»C#D»EfF#G#H»I # J #K »L tM *N #0 tP 10 #R #S »T #U >0 fW #X #Y #Z fZZZ 
32767 END 

Ready 


RUNNH 

LETTER IS? J 

LETTER IS NUMBER 10 IN ALPHABET 

Ready 

RUNNH 

LETTER IS? 0 
IMPROPER INPUT 

Ready 

RUNNH 

LETTER IS? X 

LETTER IS NUMBER 24 IN ALPHABET 

Ready 

RUNNH 

LETTER IS? CC 
IMPROPER INPUT 


Ready 

LISTNH 

100 INPUT 'W0RD'5Y$ 

no Xf=" 

120 FOR IX =0X MHILE X$<=Y$ 8c 
\ READ X$ & 

\ NEXT IX 

130 IF IX = IX THEN PRINT 'IMPROPER INPUT' & 

\ GO TO 32767 

140 PRINT 'WORD BEGINS WITH LETTER';IX-IX 

500 DATA A >B fC »D »E >F »G »H f I »J »K *L »M *N »0 >P »0 tR >S iT »U *W >X >Y >Z »ZZZ 
32767 END 


Ready 

RUNNH 

WORD? SECOND 

WORD BEGINS WITH LETTER 19 


Ready 


RUNNH 

WORD? /MESSAGE 
IMPROPER INPUT 


Ready 
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13.6 Statement Modifiers 


BASIC—PLUS provides five statement modifiers to increase the flexibility 
and ease of expression in a program line: IF, UNLESS, FOR, WHILE, and 
UNTIL. Append these modifiers to program statements to conditionally 
execute statements or create implied FOR loops. All statement modifiers 
operate on only one statement. 

Where possible, use statement modifiers instead of IF statements and loops. 
Your programs will be more efficient. 

13.6.1 IF Statement Modifier 

The IF statement modifier has the form: 

<statement> IF <condition> 

It is analogous to the form IF <condition> THEN <statement>. 

For example: 

10 PRINT X IF XOO 

This statement is the same as: 

10 IF XOO THEN PRINT X 

BASIC-PLUS executes this statement if the condition is true. 

Because the IF statement modifier affects only one statement, you can use 
fewer line numbers in a program when you use IF statement modifiers 
instead of IF statements. Each line number in a program uses memory 
space; thus, using fewer line numbers makes a program more efficient. For 
example, suppose you want to print two values, X and A. You want to print 
X only if a specified condition is true, but you always want to print A. To 
write this code using an IF statement, you need two line numbers: 

10 IF XOO THEN PRINT X 

20 PRINT A 

If you write these statements on a multi-statement line, A is printed 
only when XoO is true. Otherwise, control goes to the next line in the 
program: 

10 IF XOO THEN PRINT X & 

\ PRINT A 
20 END 

On the other hand, you can write this code using one line number when you 
use the IF statement modifier: 

10 PRINT X IF XOO & 

\ PRINT A 
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When a statement modifier appears to the right of an IF-THEN statement, 
the modifier operates on either the THEN clause or the ELSE clause, 
depending on the modifier’s placement to the left or right of ELSE. For 
example: 

100 IF 1=1 THEN PRINT "HELLO" ELSE PRINT "BYE" IF 2=2 

This statement prints HELLO because the test 1 = 1 is true. The modifier 
IF 2=2 is also true, but it applies only to the ELSE clause and is never 
tested. You cannot include an ELSE clause when using IF as a modifier. 

You can use several modifiers within the same statement. For example: 

70 PRINT X(I»J) IF I=J IF X<I»J)<>0 

Line 70 prints the value of X(I, J) only if the value of X(I,J) is not zero and if 
I equals J. When more than one modifier is on a line, the modifiers are 
executed in a right-to-left order. The term nested modifiers describes this 
situation. 

13.6.2 UNLESS Statement Modifier 

The UNLESS statement modifier causes a statement to be executed if a 
condition is false. It has the form: 

<8tatement> UNLESS <condition> 

This form simplifies the negation of a logical condition. For example, the 
following statements are equal: 

10 PRINT A UNLESS A=0 
10 PRINT A IF NOT A=0 
10 IF NOT A=0 THEN PRINT A 
10 IF AOO THEN PRINT A 


13.6.3 FOR Statement Modifier 

The FOR statement modifier creates an implied FOR loop on one line. This 
modifier has the form: 

<statement> FOR <variable> - <exp> TO <exp> [STEP <exp> ] 



An example that uses none of the optional elements is: 


10 PRINT I. SQR(I) FOR 1=1. TO 10. 
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This statement is equivalent to the following FORr-NEXT loop: 


20 FOR 1 = 1 TO 10 8. 

\PRINT I »SOR< I) 8. 
\NEXT 1 


NOTE 

An implied FOR loop executes only one statement in the 
program. 

Like all modifiers, a FOR modifier in an IF statement operates only on the 
associated THEN or ELSE clause. It never operates on the conditional 
expression to the left of THEN. Thus, if you intend to print nonzero values 
in a matrix X(IOO), the following program does not operate properly: 

10 DIM XdOOZ) 

15 READ XdX) FDR IX=1X TO lOOZ 

20 IF XdXlOO, THEN PRINT I%;XdX>; FOR IX = 1X TO lOOX 

The implied FOR loop at line 20 applies only to the THEN PRINT... part of 
the statement and not to the IF... part. The first value of X that the system 
tests is X(IOO), since I remained at 100 from statement 15. 

For proper operation, line 20 should be a PRINT statement with nested 
modifiers: 

20 PRINT IX;XdX)» IF XdX)<>0. FOR IX=1X TO lOOX 

In this form, the nested modifier rule tests and prints the values of X(I%) 
appropriately. 

13.6.4 WHILE Statement Modifier 

The WHILE statement modifier repeatedly executes a statement while a 
specified condition is true. It has the form: 

<statement> WHILE <condition> 

For example: 

10 LET X = X*2X WHILE X-'2X<1B000 

The preceding line 10 is a more efficient way of writing the loop than the 
following WHILE-NEXT construct: 

10 WHILE X*2X<16000 

20 LET X=X‘2X 

30 NEXT 
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The WHILE statement is also more efficient than the following IF-THEN 
construct: 

10 LET X=X“2Z & 

IF X‘2<1G000 THEN 10 

The WHILE modifier (and the UNTIL modifier described in Section 13.7.5) 
is useful only in iterative loops, where the logical loop structure modifies 
the values that terminate the loop. This differs significantly fi-om FOR 
loops, where the control variable automatically iterates. A WHILE state¬ 
ment does not automatically increment a control variable. The following 
infinite loops never terminate: 

10 X = X+1. WHILE KIOOO 

15 PRINT I»A(I) WHILE A<I)<>0 

In both cases, the program fails to change the values that terminate the 
loop. 

A correct use of the WHILE modifier is: 

no X = X+1. WHILE X<100. 

120 PRINT X 
327B7 END 

Ready 

RUNNH 

100 

Ready 


13.6.5 UNTIL statement Modifier 


The UNTIL statement modifier repeatedly executes a statement until a 
condition is true. It has the form: 

<statement> UNTIL <condition> 

For example: 

10 X=X+1. UNTIL X<>S0R(X*2Z) 

20 PRINT X 

The preceding example is more efficient than the UNTIL-NEXT construct 
in this example: 


100 

UNTIL 

X<>S0R(X*2X) 

200 

X*X+1• 


300 

NEXT 


400 

PRINT 

X 
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The UNTIL statement is also more efficient for this loop than the 
IF-THEN-ELSE construct: 


100 IF X = S0R(X*2Z) THEN GO TO 110 ELSE GO TO 130 

110 X = X+1. 

120 GO TO 100 

130 PRINT X 


13.6.6 Multiple Statement Modifiers 

You can use more than one modifier in a single statement. BASIC-PLUS 
processes multiple modifiers from right to left. For example: 

lOO LET A=B IF A>0 IF B>0 

Line 100 is equivalent to each of the following: 


100 

IF 

B>0 THEN IF A>0 THEN 

ID 

II 

<I 

100 

IF 

B>0 AND A>0 THEN LET 

1> 

II 

CD 

100 

IF 

B<=0 THEN 150 


no 

IF 

A<=0 THEN 150 


120 

LET A=B 


150 

! TEST OF A AND B COMPLETE 


The following statement causes BASIC-PLUS to read a two-dimensional 
matrix (M by N) one row at a time: 


150 READ A<I»J) FOR J=1 TO M FOR 1=1 TO N 


Each of the following examples is equivalent to the preceding line: 


150 NAT READ A(N>M) 


150 

FOR 1=1 TO 

N 

160 

FOR J=1 TO 

M 

170 

READ Ad fJ) 


180 

NEXT J 


190 

NEXT I 



Section 13.6.3 describes the interaction of FOR and IF modifiers. 

13.7 Error Handling 


BASIC—PLUS detects certain errors during program execution. These 
errors fall into two broad areas: 


1. Computational errors (such as division by 0) 

2. I/O errors (such as reading an end-of-file character (CTRL/Z) as input 
to an INPUT statement) 
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BASIC—PLUS normally does two things when it detects an error: it prints 
an error message and terminates your program. However, BASIC-PLUS 
allows you to continue program execution after it encounters some errors. 
In these cases you can use the ON ERROR GOTO statement to tell 
BASIC-PLUS that a subroutine exists at a specified line number to analyze 
errors and attempt to recover from them. This section describes ON ERROR 
GOTO and two other features used in error handling, the RESUME state¬ 
ment and the ERL variable. 

13.7.1 ON ERROR GOTO Statement 

The format of the ON ERROR GOTO statement is: 

ON ERROR GOTO [ <line number> ] 

Place this statement before any executable statements that will use the 
error handling routine. If an error occvirs, the system interrupts execution 
of your program and transfers control to yovir error subroutine at the line 
number indicated. The variable ERR assumes one of the values listed in 
Appendix C. 

When BASIC-PLUS encounters an error in your program, it checks to see 
if the program has executed the ON ERROR GOTO statement. If not, a 
message prints at your terminal and the program proceeds (that is, if the 
error does not terminate execution). If the ON ERROR GOTO statement 
was executed, the program continues at the specified line number. The 
program can test the veiriable ERR to discover what error occurred and to 
decide what action to take. 


NOTE 

An ON ERROR GOTO statement with an incorrect target 
statement number can cause error messages that are confus¬ 
ing or inappropriate. 

13.7.2 RESUME Statement 

The RESUME statement in an eiror handling routine is like a RETURN 
statement in a subroutine. After the error handling routine has processed 
the error, the RESUME statement allows your program to exit from the ON 
ERROR GOTO routine and continue execution. The RESUME statement 
causes execution to be continued at the program line that caused the error. 
Place the RESUME statement at the end of the error handling routine. The 
format of the RESUME statement is: 

RESUME [<line number>] 

For example: 

2000 RESUME 
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Line 2000 restarts your program at the line where BASIC—PLUS detected 
the error. To continue execution at some other point (as for a noncorrect- 
able problem), specify the new line number at the end of the error handling 
routine. For example: 

2001 RESUME 100 

When a RESUME or RESUME 0 statement passes control to a multi¬ 
statement line, control goes to the DIM, DEF*, FNEND, FOR, NEXT, 
or DATA statement immediately preceding the statement that caused the 
error. If none of these six statements are on the line, BASIC—PLUS passes 
control to the first statement on the line. The first statement on a multi¬ 
statement line should be the one that is most likely to generate a trappable 
error. 

Consider the line: 

50 A=A+1 \ PRINT A \ FOR MX=17, TO 3Z fi. 

\ INPUT X(MX) 8. 

\ NEXT MX 

If there is an error in the INPUT statement, control passes to the preceding 
FOR statement on the same line, instead of to the first statement on the 
line. But BASIC—PLUS does not reinitialize the loop; it retries the INPUT 
statement without changing M%. 

If an error handling routine contains code that can generate errors, it 
should execute a RESUME statement before continuing to process the orig¬ 
inal error. 

13.7.3 Disabling the Error Handling Subroutine 

In certain portions of a program, you may want BASIC-PLUS, and not 
yovir program, to process errors. You can disable the error handling subrou¬ 
tine by executing one of the following statements: 

100 ON ERROR GOTO 0 

100 ON ERROR GOTO 

These statements return control of error handling to the system. In 
the second form, line 0 is assumed. Note that you should specify 0 for 
compatibility with BASIC—PLUS-2. When you execute either statement, 
BASIC-PLUS treats errors as if no ON ERROR GOTO had executed. 

Generally, your error handling subroutine will detect and handle only a 
few specific errors. It is useful to have BASIC—PLUS handle other errors as 
they occur. For this reason, your program can execute the ON ERROR 
GOTO statement inside the error subroutine. 
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When the ON ERROR GOTO 0 statement is executed in an error-handling 
routine, disabling occurs retroactively. The system reports the error that 
caused the error subroutine to execute. A message is printed as though the 
ON ERROR GOTO statement had not been in elfect. 

The following example shows how an error handling routine can help inex¬ 
perienced users interact with a BASIC-PLUS program. These users may 
not know what to type at the terminal, so the program prompts them. The 
program uses the WAIT statement to allow up to 60 seconds for the user to 
respond (see Section 13.9). After 60 seconds, the error ”?Keyboard WATT 
exhausted” signals the program that the user has not replied. Then the 
program prints additional information for the user. 

The program requests your name with the INPUT statement on line 120; 
line 110 allows you 60 seconds to respond. The system executes the ON 
ERROR GOTO statement on line 100. 

LISTNH 

100 ON ERROR GOTO 1000 & 

! SET UP ERROR ROUTINE 
110 MAIT 60 & 

! MAIT 60 SECONDS FOR REPLY 
120 INPUT 'YOUR NAME' iN» &= 

! GET STUDENT NAME 
150 STOP 

1000 ! THIS IS THE ERROR HANDLING ROUTINE 

1010 IF ERR015 THEN ON ERROR GO TO 0 & 

! MAIT ERRORS ONLY 
1020 PRINT & 

! SKIP TO NEW LINE 

1030 PRINT 'PLEASE TYPE YOUR NAME' & 

\ PRINT 'AND THEN HIT "RETURN" KEY' 

1050 RESUME & 

! TRY AGAIN 
32767 END 

If some error other than "?Keyboard WATT exhausted” (ERR =15) called 
the error subroutine, the program exits through the ON ERROR GOTO 0 in 
line 1010. This permits the system to print the appropriate error messzige 
at your terminal. Note that exiting through the RESUME at line 1050 
causes the INPUT statement to be executed again. 


13.7.4 The ERL Variable 

Sometimes you need to know the line number where an error occurred. 
After error detection, the integer variable ERL contains the line number of 
the error. (The exception is the ”?Programmable *C trap” error, (ERR = 28); 
see the RSTS/E Programming Manual. In this case ERL is not set, but the 
LINE variable is set to the line number executing when CTRL/C was 
typed.) 

For example, you can use ERL to indicate which INPUT statement caused 
an "?End of file on device” error. But you must be careful when using the 
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ERL variable. When you change or resequence the line numbers of state¬ 
ments within the program, you can alter the value of the ERL variable 
within an expression context. For example: 

100 ON ERROR GOTO 1000 

110 INPUT ' TYPE TWO NON-ZERO NUMBERS'? A»B 

120 LET X=A/B 

130 LET X=X+B/A 

laO PRINT X 

150 STOP 


• 

1000 IF ERROBl THEN ON ERROR GOTO 0 
1010 PRINT 'FIRST NUMBER WAS 0' IF ERL=130 
1020 PRINT 'SECOND NUMBER WAS 0' IF ERL=120 
1030 RESUME 32767 
327B7 END 


Ready 

RUNNH 

TYPE TWO NON-ZERO NUMBERS? 5#10 
2*5 

Stop at line 150 

Ready 

RUNNH 

TYPE TWO NON-ZERO NUMBERS? B#0 
SECOND NUMBER WAS 0 

Ready 

RUNNH 

TYPE TWO NON-ZERO NUMBERS? 0#7 
FIRST NUMBER WAS 0 

Ready 

If you move the LET statements in lines 120 and 130 to some other line 
numbers, lines 1010 and 1020 also require a change. 

13.8 System Functions 

BASIC—PLUS has several system functions that get information about or 
perform operations with the system. Table 13-1 describes these functions. 


Table 13—1: System Functions 


Function 

Meaning 

Sample Usage 

DATE$(0%) 

Returns the current day, month 
and year. 

Note that the date contains both 
upper- and lowercase letters. 

If your system uses the numeric 
date format, DATE$ returns the 
date as year, month, and day. 

PRINT DATE$(0) 
lO-Jan-79 

Ready 

76.03*22 


(continued on next page) 
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Table 13-1: System Functions (Cont.) 


Function 

Meaning 

Sample Usage 

DATE$(N%) 

Returns a character string cor¬ 
responding to a calendar date. 
The formula used to translate 
between N and the date is: 

(day of year) -I- [(number of years 
since 1970)»1000] 

DATE$(1%) = ’'Ol-Jan-70” 
DATE$(2060%) = ”29-Feb-72” 

If your system uses the numeric 
date format, DATE$ returns the 
date as year, month, and day. 

76.02.29 

TIME$(0%) 

Returns the current time of day 
as a character string. 

75 IF TIME*(0) >="058 45 PM" 
THEN PRINT "TINE TO QUIT" 

TIME$(N%) 

Returns a string corresponding 
to the time at N% minutes be¬ 
fore midnight. 

TIME$(1%) = **11:59 PM” 

or **23:59 

TIME$(1440%) = **12:00 PM” 
or **00:00 

TIME$(721%) = **11:59 AM” 
or **11:59 

N% must be less than 1441 to 
return a valid string. The system 
manager determines whether 
your system uses the AM/PM 
or 24-hour time format (for ex¬ 
ample, 02:40 PM or 14:40). 

PRINT TIME*<1Z) 

11:59 PM 

Ready 

PRINT TIME*(1400Z) 

12:40 AM 

TIME(0%) 

Returns the clock time in sec¬ 
onds since midnight. 

25 IF TIME(O)>43200 

THEN PRINT "AFTERNOON" 

TIME(1%) 

Returns the central processor 
(CPU) time used for the job in 
0.1 second quanta. 

10 IF TIME( 1) >30 THEN STOP 

TIME(2%) 

Returns the connect time (dura¬ 
tion of time that you have been 
logged onto the system) for the 
job in minutes. 

10 IF TIME(2» >1000 THEN STOP 

TIME(3%) 

Returns the number of kilo-core 
ticks (KCTs) that your job used. 
(See the RSTS/E System User^s 
Guide for an explanation of 
KCTs.) 

80 PRINT TIME(3> 

TIME(4%) 

Returns the device time for the 
job in minutes. The time is accu¬ 
mulated by the RSTS / E monitor. 

40 IF TIME(4) /60>2.5 THEN 90 
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The string that the TIME$ function returns conforms to standard usage. 
The string is always 8 characters in length. For 24-hour time, the format 
is "hh:mm ”, where midnight is "00:00 ” and noon is "12:00 ”. For 
AM/PM time, the format is "hh:mm xx”, where midnight is "12:00 PM” 
and noon is "12:00 M ”. Table 13-2 shows examples of these formats. 


Table 13-2: TIME$ String Examples 


24->hour 

Format 

AM/PM 
Format 

Description 

00:00 

12:00 PM 

Midnight 

00:01 

12:01 AM 

1 minute after midnight 

00:59 

12:59 AM 

59 minutes after midnight 

01:00 

01:00 AM 

1 hour after midnight 

11:59 

11:59 AM 

1 minute before noon 

12:00 

12:00 M 

Noon 

12:01 

12:01 PM 

1 minute after noon 

12:59 

12:59 PM 

59 minutes after noon 

13:00 

01:00 PM 

1 hour after noon 

23:59 

11:59 PM 

1 minute before midnight 


In addition to the functions listed in Table 13-1, BASIC-PLUS has three 
other functions that allow you to perform more complex operations with the 
RSTS/E system: 

SYS Lets you communicate with the RSTS/E monitor. 

SPEC% Performs special operations on disks, flexible diskettes, mag¬ 
netic tape, terminals, and pseudo keyboards. 


MAGTAPE Performs special operations on magnetic tape. 


These functions are described in the RSTS/E Programming Manual. 


13.9 SLEEP and WAIT Statements 

You can use two special statements in a BASIC-PLUS program: SLEEP 
and WAIT. Both statements let you suspend your program for a stated 
interval. 

The SLEEP statement has the form: 

SLEEP <expression> 
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SLEEP stispends the running program for the number of seconds that the 
expression indicates. After this period the program runs again. Thus, you 
request these seconds of idle time. To call a job from SLEEP before the 
specified number of seconds expires, type a delimiter (RETURN, LINE 
FEED, FORM FEED, or ESCAPE) at your job terminal. You can also call a 
job from SLEEP at any other terminal that is opened by your job. 

The following program segment overrides line terminating delimiters and 
insures continuous SLEEP for a specified time: 

100 T=T1ME(0) 

110 SLEEP T+30-TIME(0) & 

\ IF TIME(0)-T<30 GOTO 110 
120 INPUT X 


In this program, the INPUT statement is executed only if the time elapsed 
is equal to or greater than 30 seconds. But if you type a delimiter, SLEEP is 
executed again for the length of time remaining in the original 30 seconds 
or until you type another line terminating character. 

A job is also awakened when the system manager disables logins or one of 
several other conditions occurs. See the RSTS/E Programming Manual for 
details. 

The WAIT statement has the form: 

WAIT <expression> 

WAIT sets a maximum period for the system to wait for input from your 
keyboard. If you do not type a delimiter (RETURN, LINE FEED, ESCAPE, 
or FORM FEED) within the number of seconds that the expression speci¬ 
fies, program execution continues and a "?Keyboard WAIT exhausted” 
error (ERR= 15) occurs. You can detect this error using ON ERROR GOTO. 

The WATT statement works with the INPUT statement. For example: 


LfSTNH 



10 

ON ERROR GOTO 100 



20 

WAIT 15 



30 

INPUT M6 + 16 = ' ;A 



40 

WAIT 0 



50 

IF A=32 THEN PRINT 

'RIGHT! ' 

fie 


ELSE PRINT 

'NO# TRY 

AGAIN' 


\ GOTO 10 



60 

STOP 



100 

IF ERR015 THEN ON 

ERROR GOTO 0 

110 

PRINT 'WAKE UP!' 



120 

RESUME 30 



32767 

END 



Ready 




RUNNH 




16 + 

16 =? WAKE UP! 



16 + 

16 *? 30 



UOf TRY AGAIN 



16 + 

16 «? 32 



RIGHT 

! 



8t OP 

at line 60 



Ready 
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In this example, the WATT statement at line 20 causes the system to wait 
15 seconds for keyboard input when the INPUT statement is executed. Line 
100 executes only if you fail to respond within 15 seconds. 

A WAIT statement affects the entire program. The specified wait period is 
in effect for all terminal input until another WAIT statement is executed. 
Use the WAIT 0 statement to restore the terminal to its normal state where 
no timeout occvirs. In this state, the system waits imtil a line is entered, 
however long it takes. 

13.10 CHAIN Statement 

The CHAIN statement transfers control from one BASIC-PLUS program to 
another. Use CHAIN when a program is too large to load into memory and 
run in one operation. Break the program into two or more separate pro¬ 
grams and then use the CHAIN statement in these separate programs to 
call other programs into memory to be run. 

NOTE 

This discussion of the CHAIN statement uses terms that may 
be unfamiliar to you. These terms relate to working with 
data files. Part IV of this manual discusses data files in 
detail. 

The CHAIN statement has the format: 

CHAIN <8tring> [ [LINE] <line number>] 

The string is a file specification that names the program for BASIC-PLUS 
to load, translate, and execute. Only the file name is required; all other 
parts of the file specification are optional. LINE, which means line number, 
is an optional word included for compatibility with BASIC-PLUS-2. The 
line number, if included, specifies the line where execution is to start. If 
you omit the line number, execution starts at the first line in the program. 
Consider the following examples: 

1000 CHAIN "MAIN.BAC" 

1000 CHAIN "MAIN.BAC" LINE 2000 
1000 CHAIN "MAIN.BAC" 2000 

All three statements load and execute the program MAIN.BAC. In the first 
statement, execution starts at the first line in MAIN.BAC; in the second 
and third statements, execution starts at line 2000. 

The CHAIN statement works much like the RUN command. Like RUN, it 
loads and executes a translated (.BAC) file by default. If no translated 
progreun exists, it loads, translates, and executes the corresponding source 
CBAS) file. Because .BAS files require translation each time they are run, 
it is more efficient to chain to .BAC files. The system displays an error 
message if you specify a file that does not exist. 
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You can pass data between chained programs using common memory or 
data files. Common memory (also called "core common”) is a data area in 
your job’s memory area. It can hold a string up to 127 bytes long. You use 
system function calls to put a string into this area and get it out (see the 
RSTS IE Programming Manual). Data files are described in Part IV of this 
manual. 

Before CHAIN loads a new program, it closes all open files and other I/O 
channels for the current program. Thus, the new program must open all 
files and I/O channels it needs to use. CHAIN closes I/O channels implic¬ 
itly, not explicitly, which means that the last buffer of data is not written to 
the file. It is therefore advisable to close all files explicitly with a CLOSE 
statement before chaining to another program; the implicit close can cause 
the contents of partially filled output buffers or modified virtual array ele¬ 
ments to be lost. 

Keep the following information in mind when you use CHAIN: 

1. It is recommended that you include the file type in the CHAIN state¬ 
ment, especially if you have programs with duplicate file names in your 
directory. RSTS/E supports many different programming languages 
under its various run-time systems. If you do not specify the .BAC or 
.BAS file type, it is possible for the CHAIN statement to load and exe¬ 
cute a compiled file that is not a BASIC-PLUS program. 

2. The file operations that CHAIN performs can take considerable system 
time. So use CHAIN only when necessary—^that is, only when your 
programs are too large to fit in memory. 

3. When you enter a program through the CHAIN statement, the system 
sets the STATUS variable. See the RSTS IE Programming Manual for 
more information. 

4. On RSTS/E systems with several run-time systems installed, CHAIN 
can work differently for source and translated programs. For example, 
suppose you switch to DCL, making it your job keyboard monitor. Then 
you run a translated BASIC—PLUS program using the DCL RUN com¬ 
mand. If that translated program chains to a source program, you will 
be in the BASIC—PLUS keyboard monitor after the source program is 
finished executing. On the other hand, if that translated program 
chains to another translated program, the second translated program 
returns you to ffie DCL keyboard monitor when it is finished executing. 

5. If a CHAIN statement in a nonprivileged program names a privileged 
program, the CHAIN statement should not include a line number. You 
must execute the entire chained program or else the system will not 
retain the chained program’s privilege. (There are some exceptions to 
this rule—see the RSTS IE Programming Manual.) 

6. If a CTRL/C is typed while a CHAIN statement is executing, execution 
halts. The halt always occurs, even if one or both programs have CTRL / C 
trapping enabled. 
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PART IV 
Data Handling 
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Chapter 14 

Overview of Data Handling 


Chapters 9 and 10 introduce data handling. They describe how to enter 
data into a program with the INPUT and INPUT LINE statements, using 
your terminal as the input device. They also describe the READ and DATA 
statements, where the data is contained in the program itself. While these 
techniques are satisfactory when you need to input a small amount of data, 
they are inefficient when your program has large amounts of data to 
process. 

Chapters 9 and 10 also show you how to print data on your terminal with 
the PRINT statement. This technique lets you display the results of your 
program, but it does not provide a permanent record of its output. 

Besides these disadvantages, the I/O methods described so far have 
another shortcoming. Processing data in a computer is often repetitive. 
Programs process the same data many times, changing the data each time 
it is processed. READ, DATA, and simple terminal I/O are not designed for 
this kind of repetitive processing. 

Data files can fill all these needs. They: 

• Are an efficient way to store and input data for a program to process 

• Provide a permanent record of program input and output 

• Allow you to repeatedly process data that changes each time it is pro¬ 
cessed 

• Allow different programs to share the same data 

This section of the manual describes how to work with data files in 
BASIC-PLUS. This chapter covers basic concepts, introduces the three 
types of BASIC—PLUS files, and describes the OPEN, CLOSE, NAME—AS, 
and KILL statements, which you use for all types of files. Chapters 15,16, 
and 17 describe each tjrpe of I/O in detail. 
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14.1 Files and Devices 


A BASIC—PLUS data file consists of data to be transferred between 
programs executing in memory and devices outside memory. The most com¬ 
mon peripheral devices are: 

• Terminals 

• Disks 

• Magnetic tape 

• Line printers 

• Flexible diskettes 

Disks and magnetic tape are file-structured devices; the rest are non-file- 
structured. You can store many different files on a file-structured device. 
Each file has a file specification that uniquely identifies it. In contrast, you 
specify only a device name to identify a non-file-structured device like a 
terminal or line printer. The system treats the entire device as a single 
’Tile.” 

Note that while disks and magnetic tape are file-structured devices, you 
can also use them as non-file-structured devices on RSTS/E. The RSTS/E 
Programming Manual describes special programming techniques for each 
type of peripheral device. 

14.2 Accessing a File or Device from a Program 

To access a file or device from a program, you open a file, read data, write 
data (or both), and then close the file. 

14.2.1 Opening the File 

The first step in accessing a file or device is to make it available to your 
program. You do this by "opening” it with the BASKD-PLUS OPEN state¬ 
ment. In the OPEN statement, you specify (at a minimum) the file or device 
name and a channel number, which must be an integer from 1 to 12. 

The OPEN statement makes the file or device available to your program 
by: 

• Creating a logical connection between your program and the file or 
device, called an 7/0 channel. 

• Setting aside an area in memory to be an interhiediate storage area 
between your program and the file or device. This area is called the 7/0 
buffer or the channel buffer. 
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The I/O channel is identified by the number you specify in the OPEN 
statement. You use this channel number to refer to the file or device in 
other program statements. Channels 1 through 12 are available to your 
program. The system uses channel 0 for your terminal, so you cannot open 
a file or device on channel 0. 

The I/O buffer is located in your program’s memory area; thus, opening a 
file causes your program to expand. The size of the buffer depends on the 
type of device you open. The system has a default buffer size for each 
device; the default buffer size for disks is 512 bytes. You can also specify a 
buffer size as an optional part of the OPEN statement. 

The data in the I/O buffer has the same format as it does on the storage 
device. In formatted ASCII and virtual array I/O, BASIC-PLUS performs 
all the processing necessary to make the data available to your program as 
integer, floating-point, and string data. In block I/O, however, your pro¬ 
gram controls the buffer directly. You access the data in the buffer as string 
data, and use conversion functions to make it available to your program as 
integers or floating-point numbers. You then convert numeric data back to 
string data for output. 

Besides creating an I/O channel and establishing an I/O buffer, the OPEN 
statement can also perform several other functions. For example, OPEN 
can create a file with specific characteristics or open a file in a special 
"mode.” Section 14.5 describes the OPEN statement in more detail. 

14.2.2 Reading and Writing Data 

After you open a file or device, it is available to your program. You can read 
input fmm it and write output to it. The statements you use to do this and 
the amount of processing that BASIC-PLUS performs for you depend on 
the type of file you choose to work with. 

Reading and writing data is a two-step process. When you read data, it 
moves first from the file to the I/O buffer and then from the I/O buffer to 
your program. When you write data, the path is reversed. In formatted 
ASCII and virtual array I/O, BASIC-PLUS handles the buffer. From your 
point of view, it looks like data moves directly between your program and 
the file. In block I/O, however, you control both steps in the process. 

14.2.3 Closing the File 

When you are finished using the file or device, you close it with the CLOSE 
statement, which closes the I/O channel. This action frees the space taken 
by the I/O buffer for other use and "disconnects” the file or device from 
your program. Except when you use block I/O or enter a special form of 
the CLOSE statement, CLOSE writes the data in the I/O buffer out to the 
file or device before freeing the buffer space and breaking the logical 
connection. 

The next section introduces the three t 3 rpes of BASIC—PLUS files. 
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14.3 BASIC-PLUS File Organizations 

BASIC-PLUS provides three file organizations: 

• Formatted ASCII, also called ASCII stream 

• Virtual Array 

• Block I/O 

You use different programming techniques to work with each type of file. 
Formatted ASCII files are the simplest files to work with; block I/O files 
are the most complex. BASIC-PLUS does not support RMS-11 files. 

14.3.1 Formatted ASCII Files 

If you know how to use the PRINT and INPUT statements for terminal 
I/O, you already have most of the information you need to work with for¬ 
matted ASCII files. B ASIC—PLUS handles a formatted ASCII file the same 
way it handles a terminal. 

Formatted ASCII files store ASCII characters sequentially in variable- 
length records. Each record is the same as a line on your terminal: it 
consists of a line of text followed by a line terminator, which serves as the 
record delimiter. The record delimiter can be a RETURN (carriage return/ 
line feed), a LINE FEED, a FORM FEED, an ESCAPE, or a VT (vertical 
tab). A CTRL/Z marks the end of the file. Formatted ASCII files do not 
usually contain any null characters (ASCII code 0) because the system 
discards them when it processes formatted ASCII files. 

To access a formatted ASCII file, you open it on a channel and then use its 
channel number in INPUT and PRINT statements. BASIC-PLUS handles 
the exchange of data between the file, the I/O buffer, and yoxir program, 
and also performs necessary data conversions between ASCH and numeric 
data t}rpes. 

Formatted ASCII files are sequential access files; you cannot access data 
randomly. You can store formatted ASCII files on disk and tape devices. 
See Chapter 15 for more information on working with formatted ASCII 
files. 

14.3.2 Virtual Array Files 

Virtual arrays are arrays stored on disk. Except for a few differences, which 
are described in Chapter 16, you work with virtual eirrays using same the 
progrsimming techniques you use for memory arrays. 

You can use virtual array files to store arrays that are too large to fit in 
memory. One file can contain several arrays. Each "record” in a virtual 
array file is one array element, and virtual arrays can contain real, integer, 
or string data. You access the data in the file using the same methods you 
use for memory arrays; no special input or output statements are required. 
BASIC-PLUS performs the necessary read and write operations to the disk 
and also manages the I/O buffer. 
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You can access data in virtual arrays randomly or sequentially, just as you 
access arrays in memory. You can store virtual arrays only on disk devices. 
See Chapter 16 for more information on virtual arrays. 

14.3.3 Block I/O Files 

Block I/O is the most flexible way to do I/O in BASIC—PLUS; it is also the 
most difficult to program. You will need to learn several new programming 
techniques to use block I/O. 

Block I/O files are sequential or random access files that contain a series of 
numbered records. Each record in the file corresponds to one physical block 
on the storage device. You can store block I/O files on disk or tape devices. 
The record size varies depending on the storage medium. 

When you use block I/O, BASIC-PLUS does much less processing for you 
than when you use formatted ASCII files or virtual arrays. Instead, your 
program is in control. For example, you; 

• Control read and write operations between the I/O buffer and the file 

• Operate on the data in the buffer directly 

• Define the format and location of data in each record in the file 

See Chapter 17 for a complete description of the statements and functions 
you need to use block I/O. 

14.4 Choosing an I/O Method 

The I/O method to choose depends on: 

• The nature of your application 

• The amount of time you want to spend developing the program 

Formatted ASCII and virtual arrays provide enough flexibility for many 
kinds of applications. They are also relatively easy to program because 
BASIC-PLUS does most of the special processing for you. 

Formatted ASCII I/O lets you access all devices the same way—^you do not 
have to know the characteristics of a device in order to use it. Because 
formatted ASCII files are text files, you can edit them, display them on the 
terminal, and print them on the line printer. But converting data between 
ASCII and numeric formats consumes processor time, iind ASCII data takes 
up a lot of storage space. In addition, formatted ASCII files allow sequential 
access only. 

Virtual arrays provide a random access disk file that is easy to use. They 
also allow you to work with arrays that are too large to be stored in mem¬ 
ory. However, the way your program accesses data in the array is very 
important. To use virtual arrays efficiently, you need to minimize the num¬ 
ber of disk accesses; otherwise, your program rims very slowly. Chapter 16 
provides the information you need to make efficient use of virtual arrays. 
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Block I/O provides the additional control and flexibility you need when 
your application is complex or when speed of execution is very important. 
Unlike formatted ASCII I/O and virtual arrays, block I/O lets you tailor 
your program to the characteristics of each device. You can also process any 
t 5 rpe of logical data record. 

BASIC—PLUS provides a set of tools (statements, functions, and special 
variables) for using block I/O. However, programs that use block I/O are 
more difficult to develop and debug. 

The rest of this chapter describes the basic statements for working with all 
types of files: OPEN, CLOSE, NAME-AS, and KILL. 


14.5 OPEN Statement 

The OPEN statement associates a file or device with an I/O channel num¬ 
ber. (The I/O channel is a logical entity, having no specific relationship to 
hardware.) 

A channel can be associated with either a file-structured or a non-file- 
structured device. Consider this example for a file-structured device, such 
as a disk: 


OPEN 'FOO.DAT' AS FILE «1 


An example for a non-file-structured device, such as a terminal, is: 

OPEN 'KBs ' AS FILE m2 


BASIC—PLUS permits your program to have up to 12 files open at a given 
time. Channel numbers 1% to 12% can be used with any file or device. 
(Channel number 0% specifies the terminal owned by your job.) 

The general form of the OPEN statement is: 


OPEN <string> 


FOR INPUT )1 
FOR OUTPUT) 


AS FILE 


[#] <expression> 


The <string> is either a string constant, a string variable, or a string 
expression that contains a RSTS/E file specification of the form: 

dev:[acct]filename.1yp / switch(es) 


The file name is required for file-structured devices; the device name is 
required for non-file-structured devices. All other parts of the file specifica¬ 
tion are optional. By default, the OPEN statement opens a file in your 
account on the public structure and assigns a protection code of 60. The 
OPEN statement has no default file type. 

After opening a file or device, you perform input and/or output by referring 
to the channel number. Specify the channel number in the OPEN state¬ 
ment with the integer expression after the keyword FILE. The expression 
must be an integer from 1 to 12. You cannot open channel 0 because the 
system opens your terminal on channel 0 when you log in. 
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Protection codes are normally specified only in the NAME-AS statement, 
which changes the name and protection code of an existing file (see Section 
14.7). However, protection codes can be specified as an optional part of any 
file specification. 

Use the /PROTECT switch to specify the protection code. For example; 

300 OPEN 'FILE.TYP/PR;aO' FOR OUTPUT AS FILE wlX 

The file FILE.TYP is created with a protection code of 40 and is opened on 
channel 1. 

As in previous versions of RSTS/E, you can also enclose the protection 
code in angle brackets. However, it is recommended that you use the 
/PROTECT switch. See the RSTS/E System User's Guide for more 
information. 

You can append any or all of the following options to the end of the OPEN 
statement: 

[,RECORDSIZE <expression>] [.CLUSTERSIZE <expression>] 

[,FILESIZE <expre88ion>] [,MODE <expression>] 

Options must be in the order RECORDSIZE, CLUSTERSIZE, FILESIZE, 
MODE. If options are out of order, you get the message: 

?Syntax error 

Note that except for RECORDSIZE, these options can also be specified as 
RSTS/E file specification switches. If an OPEN statement contains a 
switch and an option with the same name, the value specified in the OPEN 
statement option has precedence over the value specified in the file specifi¬ 
cation switch. 

Omitting an option is the same as specifying that option with a parameter 
of 0%. In both cases, the option’s default value is used. (The MODE option 
for non-file-structured magnetic tape is an exception; see the RSTS/E 
Programming Manual.) 

14.5.1 Forms of the OPEN Statement 

The OPEN statement has three distinct forms: 

OPEN <string> FOR INPUT AS FILE <expression> 

OPEN <string> FOR OUTPUT AS FILE <expression> 

OPEN <8tring> AS FILE <expres8ion> 

The form of the OPEN statement determines whether you open an existing 
file or create a file: 

1. An OPEN FOR INPUT statement searches for an existing file (the 
statement indicates the file is an input file). If the system does not find 
a file, it returns the error: "?Can’t find file or account” (ERR=5). 
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2. An OPEN FOR OUTPUT statement searches for an existing file and 
deletes it if found. A new file with the same name is then created. (See 
the RSTS IE Programming Manual for special OPEN modes that can 
prevent supersession of existing files or that open tentative files.) 

3. An OPEN statement without an INPUT or OUTPUT designator 
attempts to perform an OPEN FOR INPUT operation described in item 
1. If this fails, the system creates a new file. 

NOTE 

The OPEN statement does not restrict a program from per¬ 
forming both input and output operations on a disk file. Nor 
does it grant read or write access to the file. These privileges 
are controlled by the file protection code and MODE value. 
Magnetic tape and DECtape are exceptions; see the RSTS IE 
Programming Manual for more information. 

If the program cannot access the file or device, an error is returned. Table 
14-1 summarizes common errors that occur on attempted file access. 

On DECtape and magnetic tape devices, the FOR INPUT and FOR 
OUTPUT clauses restrict operations on that file to the operation specified. 

When used with disk files, OPEN FOR INPUT and OPEN FOR OUTPUT 
allow either read or write operations on the opened file. The system allows 
write access to a file if the protection code permits and if no other user has 
write access to the file. 

For example, if user 1 opens a file, he has read and write access. If user 2 
opens the same file, he has read access only; a ”?Protection violation” error 
occurs when he attempts to write on that file. When user 1 subsequently 
closes the file, no user has write access until the next open operation. User 
3 can now open the file for both read and write access, because no other 
user currently has write access to that file. 

There are two ways to open a file without gaining write access. You can 
either specify the /RONLY switch at the end of a file specification or open 
the file with the Read Only mode. (See the RSTS IE Programming Manual 
for more detail.) Both ways bypass the normal mechanism that grants write 
access. 

You can determine whether the current job has read or write access to a file 
by testing the STATUS variable immediately after the OPEN statement. 
The STATUS variable is described in Section 17.1.1. 

NOTE 

Only one user at a time can have write access to a disk file 
unless that file is opened in update mode or unguarded mode 
(MODE value = 1% or 5%). 
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Table 14-1: OPEN Statement Errors 


Value of 
ERR 

Message 

Explanation 

2 

?niegal file name 

The file name specified is not acceptable. It 
contains unacceptable characters, or else it 
violates the file specification format. 

4 

?No room for user on device 

The directory space of your device is 
exceeded, or the device is too full to accept 
further data. 

5 

?Can’t find file or account 

The file or accoimt number is not found on 
the specified device. 

6 

?Not a valid device 

The device specification is not valid for one 
of the following reasons: 

1. The unit number or its type is not in 
the system configuration. 

2. The logical name has no associated 
physical device and is thus untranslat¬ 
able. 

8 

?Device not available 

The specified device exists on the system, 
but you cannot assign or open it for one of 
the following reasons: 

1. The device is reserved for another job. 

2. You lack necessary access privileges for 
the device. 

3. The device is disabled. 

4. The device is a keyboard line for pseudo 
keyboard use only. 

10 

?Protection violation 

You do not have access privileges for the 
file. 

14 

?Device hung or write- 
locked 

Check the hardware condition of the device 
you requested. Possible causes of this error 
include a line printer out of paper or a high¬ 
speed reader off-line. 

17 

?Too many open files on xmit 

The system permits only one open output 
file per DECtape drive and only one open 
file per magnetic tape drive. 

32 

?No buffer space available 

You accessed a file and the monitor requires 
one small buffer to complete the request. No 
small buffer is available. 

39 

?Magtape select error 

When you attempted to access a magnetic 
tape drive, it was off-line. 

46 

?Illegal I/O channel 

You specified an I/O channel number out¬ 
side the range of integers 1 through 12. 
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14.5.2 File-Structured and Non-Fiie-Structured Devices 


RSTS/E distinguishes between file-stinctured devices (disk, DECtape, and 
magnetic tape) and non-file-structured devices (terminals, for example). 
You handle them differently when you want to find or create a file. 

For a file-structured device, you must include both a device name (or accept 
the default public disk structure) and a file name in the file specification 
string of the OPEN statement. 

For non-file-structured devices, the device name identifies a file; file name 
and type, if specified, are ignored. For example: 

KB54; Specifies keyboard number 54. 

L P1: Specifies line printer unit 1. 

LPI s FI LE Same as LPl:; the file name is ignored. 

0X1: Specifies diskette imit 1. 

You need not specify the default device (the public disk storage area). 

You can also open a file-structured device in non-file-structured mode. For 
example: 

IBO OPEN 'DKZ:' AS FILE 5% 

Line 160 opens a disk in non-file-structured mode. The RSTS/E 
Programming Manual describes device-dependent features. 


14.5.3 OPEN Statement Options 

The next four sections describe the RECORDSIZE, CLUSTERSIZE, 
FILESIZE and MODE options of the OPEN statement. As these are sophis¬ 
ticated file-handling tools, new users may wish to skip these sections for 
now and continue with Section 14.6. 

14.5.3.1 RECORDSIZE Option 

When you open a file, BASIC—PLUS creates an I/O buffer in your memory 
area to transmit data to and from the file. Normally the device determines 
the space reserved, because each device has a default buffer size. Table 
14—2 lists the default buffer size for each device. 

With the RECORDSIZE option, you can allocate more buffer space than is 
provided by the default case. However, the device may not let your program 
use additional space. 

Table 14—3 shows the buffer sizes you can specify for each device. 

The buffer size you specify should be an even number. If you specify an odd 
number, BASIC—PLUS rounds it down to the next even number. 
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Table 14-2: Default Device Buffer Size 


Device 

Default Device Buffer Size 
(characters or b 3 rte 8 ) 

Disk 

512* 

Diskette 

512 

DECtape 

510* 

Magnetic tape (DOS or ANSI) 

512** 

High-speed paper-tape reader 

128 

High-speed paper-tape punch 

128 

Line printer 

128 

Card reader 

160 

User terminal 

128 

Null device 


DMCll/DMRll 

512 

*The default buffer size may differ when you use the device as a non-file-structured 
device. 

**For ANSI magnetic tape, the system reads a value from the header label to establish 
the buffer size. 

♦**See the RSTS/E Programming Manual for more information about the null device. 


Table 14-3: Use of RECORDSIZE 





Device 

Possible Buffer Alterations 

Disk 

A disk may use any buffer size that is an integral multiple of 512 
b5rtes. 

DECtape 

DECtapes use only the first 510 bytes of the available buffer space 
(512 bytes for non-file-structured DECtape). 

Magnetic tape 
(DOS or ANSI) 

Magnetic tapes use only enough b 3 rtes for one physical magnetic 
tape record. Each physical record must be at least 14 bytes and no 
larger than the buffer size. 

High-speed reader 
High-speed pimch 
Line printer 

User Terminal 

These non-file-structured devices can use any buffer size greater 
than the default size. The card reader uses only enough bytes for 
one card’s data. 

Diskette 

Diskettes use any buffer size that is an integral multiple of 128 
bytes. 

Null device 

The null device can use any even buffer size. 

DMCll/DMRll 

The DMCll/DMRll can use any even buffer size. However, you 
usually make the I/O buffer the same size as the device’s receive 
buffer, which cannot exceed 632 bytes. You can specify the receive 
buffer size with the FELESIZE option. See the RSTS/E Program^ 
ming Manual for more information. 
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When you specify a value less than the default, BASIC-PLUS uses the 
device’s default buifer size. To get a buffer size less than the default, specify 
the desired buffer size, plus 32767%, plus 1%. Smaller buffer sizes are often 
useful when performing alternate buffer I/O (see Section 17.3.7). 

For example, to open a paper-tape reader with a buffer size of two bytes for 
use with alternate buffer I/O, t 5 npe: 

10 OPEN 'PRs' FOR INPUT AS FILE & 

RECORDSIZE 327B7Z + IT + 2T 

The RECORDSIZE option has significant advantages when you use it with 
magnetic tape and disk files. On a disk file, you can improve total through¬ 
put by using a larger buffer size. This permits a single ^sk transfer to read 
a large quantity of data. For example: 

100 OPEN "MASTER.DAT" FOR INPUT AS FILE 1X» RECORDSIZE 2048X 

If the file MASTER.DAT occupies a contiguous area on a disk, one 
2048-b5rte transfer takes place. Otherwise, the RSTS/E monitor breaks 
this quantity into as many as four 512-byte transfers, which takes longer. 
Either way, the system overhead to perform the transfer is less. 

To ensure that a file occupies a contiguous disk area, use the MODE option 
(see the RSTS/E Programming Manual) or the CLUSTERSIZE option 
described in Section 14.5.3.2. 

14.5.3.2 CLUSTERSIZE Option 

The CLUSTERSIZE option applies to disk and ANSI magnetic tape files 
that you create with an OPEN or OPEN FOR OUTPUT statement. The 
following description applies to disk files. (Refer to the RSTS/E System 
UsePs Guide for device-specific information and the RSTS /E Programming 
Manual for more details on cluster sizes.) 

The RSTS/E system divides each disk into a number of 256-word blocks. 
Each block is assigned a unique logical block number starting at 1. Block 0 
of each disk is reserved for a bootstrap record and is not used by any file. 
Logical block numbers are assigned such that block n is contiguous with 
blocks n +1 and n-1. 

Contiguous blocks taken together as a unit are called a cluster. RSTS/E 
permits clusters to have 1, 2, 4, 8,16, 32, 64, 128 or 256 blocks. When the 
disk is initialized (cleared for use on RSTS/E), a minimum cluster size is 
established. This minimum cluster size, called the pack cluster size, can be 
1, 2, 4, 8, or 16 blocks. 

To compute the optimal CLUSTERSIZE for a file, divide the file size by 7 
and round the result to the next power of 2 (maximum). If you get a result 
larger than 256, then either use a cluster size of 256 or make the entire file 
contiguous. The CLUSTERSIZE cannot be less than the minimum, or pack, 
cluster size. 
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For each file on the system, an entry is made in the User File Directory, or 
UFD. This entry contains the retrieval information for the file: file name, 
cluster size, and a sequential list of clusters belonging to that file. 

The maximum size of a UFD is seven times its cluster size, which is estab¬ 
lished when the account is created. The UFD cluster size can be 1, 2,4,8, or 
16 blocks. A UFD on a disk cannot exceed 112 (decimal) blocks (28,672 
words). If files are a minimum size (7 or fewer clusters), a UFD clustered as 
16 can hold a maximum of 1157 files. To keep the list of file blocks short, 
the UFD contains a one-word entry for the first block of each cluster. The 
first block number of the cluster and the cluster size is sufficient to deter¬ 
mine the blocks in the cluster. 

Because of the size limit on the UFD, it is a good idea to specify large 
cluster sizes for large files. In an extreme example, the UFD would be filled 
by a single file of 24,283 blocks where the file cluster size is one block. 
However, with a cluster size of 256 blocks, only 128 words of the UFD are 
required to describe this file. 

Omitting the CLUSTERSIZE option is equivalent to specifying CLUSTER- 
SIZE 0%. This assigns a cluster size equal to the pack cluster size for the 
disk where the file resides. If you attempt to specify a cluster size less than 
the pack cluster size or if it is not a power of 2, an "?Illegal cluster size” 
error message (ERR=23) results. 

When you specify a negative CLUSTERSIZE for a file, the system uses 
either the absolute value of the argument specified or the pack cluster size, 
whichever is greater. A negative cluster size is useful in a progrsun that 
you plan to run on both large and small systems or on systems that have 
mixtures of large and small disks. For example, suppose you want to create 
files with a cluster size of 2. If you specify —2, the program can also create 
files on disks where the pack cluster size (the minimum cluster size permit¬ 
ted) is greater than 2. For these disks, the system will use the pack cluster 
size instead of the cluster size you specify. 

A sample use of the CLUSTERSIZE option is: 

100 OPEN "MAT.DAT" FOR OUTPUT AS FILE •IX. CLUSTERSIZE 128X 

In this example, the file MAT.DAT is created with a cluster size of 128 
blocks. MAT.DAT is initially 0 blocks long and is extended as needed in 
128-block increments. 

The system extends files a cluster at a time. Since clusters are contiguous 
blocks, you may not find enough contiguous blocks to extend the file (even 
if enough free, but not contiguous, blocks are available on the disk). If not, 
the system prints the "?No room for user on device” error message 
(ERR=4). You should be aware of this when creating a file with a cluster 
size larger than the pack cluster size (the minimum cluster size for that 
disk). 

As another example: 

100 OPEN "DATA" FOR OUTPUT AS FILE 8, 

RECORDSIZE 2048X* & 

CLUSTERSIZE AX 
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When the system can read or write multiple blocks in a single transfer, the 
RECORDSIZE option improves disk throughput (see Section 14.5.3.1). By 
creating the file with a cluster size of 4 (2048 bytes per cluster), you guar¬ 
antee that virtual blocks 1-4, 5-8, and so forth are contiguous on the disk. 
These file clusters could be read or written in a single operation. 

14.5.3.3 FILESIZE Option 

You can preextend a disk file (and only a disk file) by using the FILESIZE 
option in sui OPEN statement. The format for the FILESIZE option is: 

OPEN <string> [FOR OUTPUT] AS FILE <expr> .FILESIZE <expr> 

For example: 

100 OPEN 'VALUES' FOR OUTPUT AS FILE «3X» FILESIZE SOX 

The data file VALUES is opened and automatically preextended to 50 
512-byte blocks. 

The argument used with the FILESIZE option must be an integer. To spec¬ 
ify a file size of N, where N is between 32768 and 65535 inclusive, specify 
the FILESIZE argument as 32767% + 1% + (N-32768). This expression 
converts a signed integer to its unsigned value; that is, its value where bit 
15 is 32768 instead of -32768. (See Sections 11.1 and 11.2 for more informa¬ 
tion on the internal format of integer data.) 

You can use the FILESIZE option to preextend files to 65535 blocks only. If 
you want to preextend a file to more than 65535 blocks, use the /FILESIZE 
switch in the file specification: 

100 OPEN 'VALUES/FILESIZE;70000' FOR OUTPUT AS FILE «3X 

See the RSTS/E System Usefs Guide for more information about the 
/FILESIZE switch. 

You can also use the FILESIZE option on ANSI magnetic tape files, but for 
a different purpose than described here. See the RSTS/E Programming 
Manual, 

14.5.3.4 MODE Option 

The OPEN statement allows another option: the MODE field. The format of 
the OPEN statement, including the MODE field, is: 



OPEN <string> 


The MODE option establishes device-dependent properties of the file. See 
the RSTS/E Programming Manual for device-dependent features. 
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14.6 CLOSE Statement 


The CLOSE statement terminates I/O between a BASIC—PLUS program 
and a peripheral device. After execution of a CLOSE, BASIC-PLUS 
reclaims the buffer space assigned to the file and closes the I/O channel 
between your program and the file. It is good progra mmin g practice to close 
all I/O channels before program execution ends. 

The CLOSE statement has the form: 

CLOSE [#] <expression> [,[#] <expression> ,...] 

The <expression> is the channel number of the file to close. You can close 
any number of files with a CLOSE statement. To close more than one file, 
separate the expressions by commas. For example: 

240 CLOSE «10Z 

250 CLOSE «2Z. «4Z 

2G0 CLOSE IZ FOR IZ = IZ TO 12Z 

Line 240 closes the file open on I/O channel 10. Line 250 closes the files 
that are open on I/O channels 2 and 4. Line 260 closes all I/O channels 
available to your program. 

You can specify two kinds of CLOSE operations in BASIC-PLUS, a normal 
CLOSE and a CLOSE with a negative channel number. 

14.6.1 Normal CLOSE 

To specify a normal CLOSE, simply list the channel numbers of the files to 
close, as shown in the preceding examples. 

The I/O method you use determines the action of a normal CLOSE. In a 
normal CLOSE of a formatted ASCII or virtual array file, BASIC—PLUS 
writes the contents of the I/O buffer out to the file before closing it. In block 
I/O, however, your program controls the I/O buffer; thus, a CLOSE state¬ 
ment does not write the buffer out to the file before closing it. 

14.6.2 CLOSE with a Negative Channel Number 

When you use a negative channel number in the CLOSE statement, 
BASIC-PLUS does not write the contents of the I/O buffer out to a format¬ 
ted ASCII or virtual array file before reclaiming the buffer space assigned 
to the file. (This is the type of CLOSE that a CHAIN statement performs.) 

This type of CLOSE is useful if the last operation you perform on the file 
(either a read or a write) could place erroneous information in the file or if 
the last block of the file might not fit on the output device. 
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A sample program segment that uses a CLOSE with a negative channel 
number is: 


10 EXTEND 


9000 ON ERROR GOTO 19000 
9100 CLOSE CHANT. 

9200 GOTO 327G7 

19000 IF ERL=9100T AND & 

ERR=A2 & 

THEN CLOSE -CHANT 

19010 PRINT "END OF FILE HAS BEEN LOST" 
19020 RESUME 32767 
32767 END 


This example shows part of a program that writes data to a disk. The disk 
may be so full that there is no room for the last block of data from the file. 

When the CLOSE statement is executed, it is possible that the final buffer 
of data to be written to the output file might not fit. In this case, program 
execution goes to line 19000, and the program checks to see if that was the 
problem. If so, the program performs the CLOSE with a negative channel 
number to suppress the output of the remaining data. The program then 
prints a message to notify you that the output file does not contain all the 
expected data. 

You can also use a negative channel number to close a channel where a 
tentative file has been opened. This type of CLOSE (which is especially 
useful for temporary work files) deletes the tentative file. See the RSTS/E 
Programming Manual for more information. 

14.7 NAME-AS Statement (File Protection and Renaming) 

The NAME-AS statement renames or assigns protection codes to a disk 
file. This statement can be used only by someone who has write access to 
the file. The format of the statement is: 

NAME <stTing> AS <8tring> 

The file specified in the first string is renamed to the ffle specified in the 
second string. When the file is on a device other than the system disk, you 
must specify the device in the fiirst string and, optionally, in the second 
string. NAME-AS has no default file type. You must specify the file type in 
both strings if there is a file t}^ in the old file name or if you want one in 
the new file name. For example: 

110 NAME "DMOsOLD.BAS" AS "NEW.BAS" 


This statement is equivalent to: 

no NAME "DMOsOLD.BAS" AS "DMOsNEU.BAS" 
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However, the next statement is not advised because FILE2 has no file type 
for the system to recognize: 

ISO NAME "FILEl.BAS" AS "FILE2" 

Use: 

ISO NAME "FILEl.BAS" AS "FILE2.BAS" 

You can specify a file protection code as part of the second string. 
the protection code in angle brackets (<>) or use the /PROTECT switch. 
(The /PROTECT switch is the recommended method.) If you specify a new 
file protection code, the new code is assigned to the renamed file. If you do 
not specify a new protection code, the old protection code is retained. See 
the RSTS/E System User's Guide for a complete description of protection 
codes. 

The following statements both change the protection code of the 
file FILE.TYP on the system disk to 40. The first statement uses the 
/PROTECT switch; the second uses angle brackets. 

200 NAME "FILE.TYP" AS "FILE.TYP/PR:40" 

200 NAME "FILE.TYP" AS "FILE.TYP<flO>" 

The next statement changes the name of the file ABC.BAS on DM0: 

200 NAME "DMO:ABC.BAS" AS "XYZ.BAS" 


NOTE 

You cannot use NAME—AS to change the device or account 
in which the file resides. 

Because you cannot transfer a file from one device to another 
with the NAME—AS statement, you need not specify the 
device (DM0: in the previous example) twice. The system 
generates an error if you specify a device other than the old 
one. 

See Section 5.2.2 for more information about the NAME-AS statement. 

14.8 KILL Statement 

The KILL statement has the form: 

KILL <stTing> 

KILL deletes the file that is named in <string> from your account. You 
can no longer open this file. If already open, the file remains available until 
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it is closed. For example, when you complete work with the file XYZ.DAT 
on the system disk, you can remove the file from storage by executing the 
statement: 

aSO KILL "XYZ*DAT” 

You cannot KILL a file that is write-protected against you. 

See Section 5.4.2 for more information about the KILL statement. 
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Chapter 15 

Formatted ASCII Input and Output 


This chapter describes formatted ASCII I/O, the simplest way to do I/O in 
BASIC-PLUS. If you know how to use PRINT and INPUT for terminal I/O, 
you already have most of the information you need to do formatted ASCII 
I/O to other devices. By combining the PRINT and INPUT statements with 
the OPEN statement, you can: 

• Store formatted ASCII data in disk and magnetic tape files 

• Read data from these files 

• Do formatted ASCII I/O to line printers or other devices 

Be sure to close the file or device with the CLOSE statement when you 
finish using it. 

Formatted ASCII files are sequential access files; they do not allow you to 
access data randomly or to update data without copying from one file to 
another. 

This chapter reviews the basic forms of the PRINT and INPUT statements, 
describes their more advanced forms, and shows you how to use them with 
the OPEN statement. 

15.1 PRINT Statement 

Earlier chapters show you how to use the PRINT statement in its basic 
form to print numeric or string data at your terminal. This section reviews 
this information. It also describes: 

• How to use PRINT to write formatted ASCII output to a disk file or other 
device 

• How to tailor the format of output with the PRINT—USING statement, an 
optional BASIC-PLUS feature 
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The basic form of the PRINT statement is: 

PRINT <list> 

This form of the PRINT statement prints a list of values at your terminal. 
The list can contain any combination of numeric and string values, and 
each item in the list can be any legal expression. When an item is not a 
simple variable or constant, BASIC-PLUS evaluates the expression before 
it prints a value. When you omit the print list, BASIC-PLUS prints a 
blank line on your terminal. 

When printing numbers, BASIC-PLUS: 

• Does not print leading zeros or trailing zeros to the right of a decimal 
point. When a whole number has a decimal point, BASIC-PLUS does not 
print the decimal point. 

• Prints numbers with up to six digits in decimal format and numbers with 
more than six digits in exponential format. 

• Prints all values with six significant digits. To print more than six signif¬ 
icant digits, use the PRINT—USING statement. 

BASIC-PLUS prints character strings without leading or trailing blank 
spaces. 

Use commas or semicolons between list elements. These characters deter¬ 
mine how output is spaced. For example: 


100 

AX = IX & 



\ BX = 2X 
\ CX = 3X 

& 

110 

PRINT AX; 

AX + BX + CX# CX 

32767 

RUNNH 

END 



1 B 2 END 

The comma prints items in print zones. BASIC—PLUS divides a terminal 
line into print zones of 14 spaces each. (The actual number of print zones is 
INT (n/14), where n is the size of the print line.) The comma moves the 
print head to the next available print zone. If the last print zone on a line is 
filled, the print head moves to the first print zone on the next line. Extra 
commas make BASIC-PLUS skip print zones. 

The semicolon prints items in a packed format. When you use the semicolon 
between list elements, BASIC-PLUS prints a positive number with a lead¬ 
ing and a trailing blank space, a negative number with a leading minus 
sign and a trailing blank space, and a string exactly as it appears inside 
quotation marks. No leading or trailing spaces are added. You can omit the 
semicolon between a string constant and another value. However, its use is 
recommended for compatibility with BASIC—PLUS-2. 

BASIC—PLUS automatically prints a carriage return/line feed at the end 
of a PRINT statement. To suppress the automatic carriage retvirn/line feed, 
place a comma or a semicolon at the end of the PRINT list. A comma causes 
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BASIC-PLUS to start printing in the next print zone; a semicolon causes 
BASIC-PLUS to start printing in the next blank space. 

See Section 9.2.2 for examples of the basic PRINT statement. 

15.1.1 Printing Data to a File or Device (Formatted ASCII Output) 

To direct output to a device other than your terminal, open the file or device 
with the OPEN statement and then use the following PRINT statement; 

PRINT #<expre88ion>,<list> 

The <expression>, which must have the same value as the expression in 
the OPEN statement, is the channel number of the output file. Its value 
must be a number from 1 to 12. The <list> can contain one or more varia¬ 
ble names, expressions, or constants separated by commas. 

For example: 

100 OPEN 'DATA1.DAT' FOR OUTPUT AS FILE «7Z 
110 PRINT *7Xf 'START OF DATA FILE' 

These lines open a file called DATA1.DAT on the disk. DATA1.DAT uses 
channel number 7. The first line in the file reads: 

START OF DATA FILE 

When you use the PRINT statement to send output to a file, BASIC-PLUS 
outputs data to the file the same way it prints data on the terminal. The 
resulting file is called a formatted ASCII or stream ASCII file. Formatted 
ASCII files are text files; you can display them on your terminal or print 
them on a line printer. 

You can use commas in the PRINT statement to format the data in the file 
in columns, just as you do when printing data on the terminal. When you 
use the comma for formatting and print to a device other than a terminal, 
each line in the file is 72 spaces wide and contains 5 print zones of 14 spaces 
each. 

To write nonprinting ASCII values into the file, use the CHR$ or the 
STRING! functions. For example, a CHR$(12%), which is a form feed char¬ 
acter, causes line printers and certain types of terminals to skip to the top 
of the next page. You can force a logical end-of-file by printing a 
CHR$(26%), which is a CTRL/Z. When you use nonprinting characters, 
keep in mind the effect they will have when read by a program or sent to an 
output device. 

If you plan to read data from the file with an INPUT statement: 

1. Be sure to write commas between data items in the file with string 
constants. For example: 

PRINT wiz* NAME$5 "»";acctz;";amount 
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2. Be sure that each output line contains a terminator. The INPUT state¬ 
ment expects a terminator (usually a carriage return/line feed) at the 
end of each line. Remember that ending a PRINT statement with a 
comma or semicolon produces an output line with no terminator. 

3. Do not print records that are more than 132 characters in length, 
including nulls, line feeds, and carriage returns. The PRINT statement 
lets you create records with more than 132 characters, but the INPUT 
statement may not read them correctly. 

You can also print data to a file or device with the the PRINT—USING and 
the MAT PRINT statements, which are described in the next two sections. 

15.1.2 PRINT-USING Statement 

On systems with the optional PRINT USING feature, you can tailor the 
format of output with the statement: 

PRINT [#<expre88ion>,] USING <string>, <li8t> 

The <expression>, which is optional, indicates the channel number of the 
output file. The <string> is either a string constant, string variable, or 
string expression that is an image of the line to be printed. This string is 
called the format field. 

The <list> shows items to be printed in the format specified by the format 
field. BASIC—PLUS prints characters in the string as they appear, except 
for the special formatting characters and character combinations described 
on the following pages. The string (or portions of it) is repeated until the 
list is exhausted. The rest of this section explains how to construct the 
format field. 

While the examples in this section show terminal output, you can also print 
to a file or device by including a channel number in the PRINT-USING 
statement. 

15.1.2.1 Exclamation Point 

An exclamation point in the format field identifies a one-character string 
field. This variable string is specified in the PRINT statement list. For 
example: 

LISTNH 

100 PRINT USING '!!!'» 'AB'» 'CD'f 'EF' 

327B7 END 

Ready 

RUNNH 

ACE 

Ready 


BASI(3-PLUS prints the first character from each of the three string con¬ 
stants or variables. Any characters beyond the first are ignored. 
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15.1.2.2 String Field 

You can specify a string field of two or more characters in the format field 
with spaces inside backslashes. On some keyboards you can produce the 
backslash character (\) by typing SHIFT/L. No enclosed spaces indicates a 
field two columns wide; one enclosed space indicates a field three columns 
wide, and so on. For example: 

100 PRINT USING '\\ \ \'» 'ABCD'> 'EFGHI' 

This statement prints: 

AB EFGH 

The first two backslashes have no enclosed spaces, hence they permit the 
printing of two characters (AB). The second two backslashes enclose two 
spaces and permit the printing of four characters (EFGH). 

15.1.2.3 Numeric Field 

Use the number character (#) in the format field to indicate numeric fields. 
You can specify any decimal point arrangement this way. Rounding (not 
truncation) is performed as necessary. For example, this statement prints 
12.35 at your terminal: 

100 PRINT USING 12.345 

Also consider the following: 

100 PRINT USING 12.345 

110 PRINT USING '*»»»,', 12,345 
120 PRINT USING 100 

RUNNH 
12 
12. 

X 100 

Ready 

Numeric fields are right-justified. If a number does not fill the allotted 
space, then spaces precede the number. When the field you specify is too 
small to print a constant or variable, BASIC—PLUS prints the percent char¬ 
acter (%) to indicate the error and then prints the number without refer¬ 
ence to the format field. 

NOTE 

If the numeric field is more than 20 character spaces larger 
than required to print a constant or variable, a ”?Print-using 
buffer overflow” non-recoverable error may occur. 

If the format field specifies a digit preceding the decimal point, at least one 
digit is always output before the decimal point. If necessary, that digit is 
zero. 
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15.1.2.4 Asterisks 


If a numeric field designation in the format field begins with two asterisks 
(**), BASIC—PLUS fills imused spaces in the format field with asterisks. 
For example; 

100 A=27.95 & 

\ 8=107.50 & 

\ C=1007.50 8. 

\ PRINT USING A»B»C 

RUNNH 

**27.95 

*107.50 

1007.50 


The asterisks (**) act as additional number characters (#), as well as filling 
imused spaces. 

You cannot use exponential format in a field with leading asterisks. Nega¬ 
tive numbers cannot be output using asterisk fill, unless a minus sign 
follows the number. The use of leading dollar signs ($$) and leading aster¬ 
isks in the same format field is not compatible with BASIC—PLUS-2. 


15.1.2.5 Exponential Format 

To print a number in exponential format, use a string that matches the 
exponential format described in Chapter 8. Use number characters (#) for 
the number and four circumflex characters D for "E±nn”, where n is the 
power expressed in two digits. For example: 

LISTNH 

100 F$='««-- 

no A=10000. 

120 PRINT USING F«.A 

Ready 

RUNNH 
lOE 03 


All format positions output a number with an exponent. BASIC-PLUS left- 
justifies significant digits and adjusts the exponent. 

15.1.2.6 Trailing Minus Sign 

If you end a numeric format field with a minus sign, BASIC—PLUS prints 
the sign of the output number after it. A blank space indicates a positive 
number. For example: 

LISTNH 

100 A=-10.5 

no PRINT USING A »A 

Ready 

RUNNH 

10*50- -10*50 
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If you do not use the trailing minus sign, you must reserve space in the 
numeric format field for the sign to precede the number. (An explicit lead¬ 
ing minus sign is treated as a literal and therefore is always included.) 

15.1.2.7 Dollar Signs 

Begin a numeric format field with two dollar signs ($$) to print a dollar 
sign immediately before the first digit of the number. For example: 

100 A=77.4a & 

\ B=304.55 & 

\ c= 22 ii,ao 

110 PRINT USING »A.B.C 

Ready 

RUNNH 
$77.44 
$304.55 
X 2211.4 

The two dollar signs ($$) provide for the printing of one additional digit in 
the number, preceded by one dollar sign ($). 

You cannot use exponential format in a field with leading dollar signs. 
Furthermore, the floating dollar character cannot output negative numbers 
unless the minus sign follows the number. The use of leading asterisks (**) 
and leading dollar signs in the same format field is not compatible with 
BASIC-PLUS-2. 

15.1.2.8 Commas 

To print commas in large numbers, insert commas in the numeric format 
field every three digits to the left of the decimal point. BASIC—PLUS reads 
a comma to the right of the decimal point as a printing character. For 
example: 

100 PRINT USING »«»»,*,»,', 12345.5» 123.456. 1 

This statement prints: 

12.345.50 123.5.1 

15.1.2.9 Insufficient Format 

If there are insufficient format characters in a field when a number is 
output, BASIC-PLUS prints a percent character (%) in the first position of 
the field, followed by the number in standard format. This usually causes 
the field to widen to the right. The entire number is printed. For example: 

100 PRINT USING **.**', 12.345. -12.5 

This statement prints: 

12.35 Z-12.5 
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There is no room in the format to print the minus sign. 

When a number has too many decimal places to print using the format 
field, BASIC-PLUS roimds the number. If the rounded number exceeds 
the format allowed, BASIC—PLUS prints the percent character (%). For 
example: 

100 PRINT USING .«#'» .125» .999 

This statement prints: 

.13 X .999 

In this case .999 rounds to 1, which exceeds the format field. 

15.1.2.10 Format Too Large 

A numeric format field may attempt to output more significant digits than 
are available. In this instance, zeros substitute for digits that follow the 
last significant digit. Six significant digits are available with the two-word, 
single-precision math package. Fifteen digits are available with the four- 
word, double-precision math package. 

When you use the PRINT-USING statement, BASIC—PLUS permits up to 
29 formatting characters for single-precision and 19 formatting characters 
for double-precision. An attempt to print fields larger than 29 or 19, respec¬ 
tively, results in the error message: 

?Print usinsr buffer overflow 


In certain cases, BASIC-PLUS truncates a number larger than the format 
field without an error message. Check for overflow before attempting to 
output numbers near the maximum size. 

15.1.2.11 Formatting and Literal Characters 

When you use the PRINT-USING statement, the usual formatting charac¬ 
ters (commas and semicolons) have no effect on the output format. The 
exception is a comma or semicolon at the end of the PRINT list that inhibits 
termination of the printed line. For example: 

LISTNH 

100 PRINT USING «« 

200 PRINT USING 2.55 

300 PRINT 'X' 

Ready 

RUNNH 
1 2 3 

2 ♦SOX 

Ready 
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The semicolon at the end of line 200 causes X to print on the same line as 
2.50. 

Characters that do not have special meanings (letters, for example) are 
printed as they appear in the PRINT-USING statement. These characters 
are called literals. An example that uses literals in the format string is: 

100 A=l.32519 B. 

\ 6=2.45457 & 

\ LET F* = ' A=#«.#« 6=«».#*' 

110 OPEN 'LP;' FOR OUTPUT AS FILE «47; 

120 PRINT «4X» USING F» . A> 6 

This example prints the following on the line printer: 

A= 1.33 6= 2.45 


15.1.3 MAT PRINT Statement 

The MAT PRINT statement, one of the optional matrix manipulation state¬ 
ments, allows easy printing of a matrix. The statement has the form: 



MAT PRINT (#<expre8sion>,] <matrix name> 


The optional <expression> is the channel number of the output file. 

BASIC-PLUS prints matrices to a file the same way it prints them on a 
terminal. For example: 

100 DIM A(16) 

120 OPEN 'MAT.DAT' AS FILE nZX 
150 MAT PRINT *ZX, A(15) 

This example prints elements 1 through 15 of the matrix A to the file 
MAT.DAT. One element appears on each line in the file. 

If the specified matrix name is unsubscripted, BASIC-PLUS prints the 
entire matrix (except for the zero elements). Use subscripts to indicate the 
maximum size of the matrix to be printed. 

You can enter a semicolon after the matrix name to indicate that the val¬ 
ues are to be printed without additional spaces between them. You can also 
use a comma to indicate that you want each element printed in its zone. For 
example: 

100 DIM A(10>10)» B<10>20) 

no MAT PRINT a; & 

! PRINT MATRIX A IN PACKED FORMAT 
120 MAT PRINT B(10»10)» & 

• 10*10 MATRIX PRINTED 5 UALUES PER LINE 
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This example prints a lO-by-10 matrix with no additional spaces between 
elements and then a widely spaced lO-by-10 matrix. 

BASIC—PLUS can also print row and column matrices. For example: 


10 DIM A(5) . B(10) 

20 MAT PRINT A; & 

! PRINT MAT A ON ONE LINE 
30 MAT PRINT B & 

! PRINT IN COLUMN FORMAT 


Ready 

RUNNH 

0 0 0 0 0 
0 
0 
0 
0 
0 
0 
0 
0 
0 
0 

Line 20 prints A as a row matrix, closely packed. Line 30 prints B as a 
column matrix. Use a comma to print a row matrix with one value per print 
zone: 

MAT PRINT A» 


BASIC-PLUS prints the matrix A as a row matrix (five values per line at 
your terminal). 


15.1.4 PRINT Functions 

The CCPOS and TAB functions format simple and complex PRINT 
statements: 

Function Description 


CCPOS(X%) 

or 

POS(X%) 

TAB(X%) 


Returns the current position on the output line, where X% is an I/O chan¬ 
nel number in the range 0 to 12. CCPOS(0%) or POS(0%) returns the value 
for your terminal. Although the two functions are equivalent, CCPOS is 
preferred for compatibility with BASIC-PLUS-2. 

Tabs to position X% in the print record. For example, a standard terminal 
has 72 printable columns numbered 0 through 71. TAB(4%) outputs 
enough spaces to move the print head to column 4. If the print head is past 
position 4, no spaces are output. 


The following example shows the actions of CCPOS and TAB: 


100 PRINT 'X'l TABdOZ)? CCPOSCOX) 
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This statement prints X at position 0, tabs to position 10 and prints the 
current position on the output line, which is 10: 

X 10 

position 0^9 spaces f positions 10 and 11 


The following example shows a use of CCPOS in a program: 

PRINT IF CCP0S(0X)<>0 

This statement guarantees that the next PRINT statement will start print¬ 
ing at the left margin. The statement tests the cvurent position of the print 
head on the terminal. If the cvirrent position is at the left margin (that is, 
CCPOS(0%) = 0), nothing happens. If the current position is anywhere else 
on the line, the program (>erforms a carriage return/line feed to retmn the 
print head to the left margin. This technique is useful for printing prompts 
or messages at the left margin. 

NOTE 

CCPOS counts characters. It does not keep track of escape 
sequences for different types of terminals. ITius, CCPOS may 
return incorrect results if you are using escape sequences for 
cursor control. 

15.2 INPUT Statement 

The INPUT statement enters data from an external device (such as your 
keyboard or a disk) to a running program. The statement’s full form is: 

INPUT [#<expression>,] <variable li8t> 

The optional <expression> is the channel number of the input file. See 
Section 15.2.1 for more information. 

When you omit the channel number, your terminal (channel 0) is the input 
device: 

INPUT <variable list> 

This form prints a question mark (?) at your terminal. The system then 
waits for you to respond with the values of string or numeric variables. You 
can enter one value at a time or you can enter a list of values separated by 
commas. If you do not type enough values, the system prints another ques¬ 
tion mark (?). If you tjrpe too many values, excess values are ignored. 

You can insert printed messages between the variables you wish to input. 
For example: 

100 INPUT 'YOUR NAME IS' i N»» 'ACCOUNT NUMBER'5A>'THANK YOU' 
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When this statement is executed, it causes the following interaction at the 
terminal: 


RUNNH 

YOUR NAME IS? JOE 
ACCOUNT NUMBER? 3-37556 
THANK YOU 

Ready 


NOTE 

Using more than one prompting message in an INPUT state¬ 
ment is not compatible with other versions of BASIC. 


ON ERROR GOTO statements can be used to trap recoverable errors that 
occur when an INPUT statement is executed. The following errors occur 
most frequently. 


Error 

Description 

Examples 

%Data format error 
(ERR = 50) 

Data input in an 
illegal form 

3.4.5 or $2 or #16 or 2;3 or LORA input 
for a numeric variable; "HELLO” 'THERE” 
input for a string variable: 



10 INPUT "TYPE A STRING’S Ai 

RUNNH 

TYPE A STRING? "HELLO" "THERE" 
IData format error at line 10 
TYPE A STRING? CAT 



Ready 

?Illegal number 
(ERR = 52) 

Overflow or 
underflow 

3E+66 or —23 

?End of file on device 
(ERR = 11) 

Input CTRL/Z 

"Z 


BASIC—PLUS assigns values to variables as you input them. You can 
assign multiple variables by separating them with commas in the INPUT 
variable list. Similarly, use commas or the RETURN key to separate values 
as you input them from the keyboard. For example: 

100 INPUT X.Y.2 

110 PRINT X»Y»Z 

RUNNH 
? 3.16 
? 14.92 

3.14 14 92 
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Do not use commas within a single number; BASIC-PLUS ignores charac¬ 
ters input beyond a comma unless another variable is assigned. For 
example: 


Right 

LISTNH 

100 INPUT R &C 
\ PRINT R 

Ready 

RUNNH 
? 25902 
25902 

Ready 


Wrong 

LISTNH 

100 INPUT R 8c 
\ PRINT R 

Ready 

RUNNH 
? 25 ,902 
25 

Ready 


Use quotation marks (”) with string variables when you want to preserve 
embedded commas. For example: 


Right 

LISTNH 

100 INPUT M$ & 

\ PRINT M$ 

Ready 

RUNNH 

? 'MOUSE# MICKEY' 
MOUSE# MICKEY 

Ready 


Wrong 

LISTNH 

100 INPUT M$ fie 
\ PRINT M$ 

Ready 

RUNNH 

? MOUSE# MICKEY 
MOUSE 

Ready 


15.2.1 Reading Data from a File or Device 

You can open a file or device for input with the OPEN statement and then 
use the INPUT statement to make BASIC—PLUS read input from that file 
or device. 

Use the following form of the INPUT statement after an OPEN statement: 
INPUT #<expre8sion>,<variable list> 


The <expression> must have the same value as the expression used in the 
OPEN statement. As in the OPEN statement, this expression is the chan¬ 
nel number of the input file. Its value must be a number from 1 to 12. The 
<list> contains one or more variable names separated by commas. 
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The following example shows the use of OPEN and BMPUT. This simple 
program opens a file, reads three values from it, prints the values on the 
terminal, and closes the file. The file must be a formatted ASCII file. When 
BASIC-PLUS reads the file, it interprets the data in the file exactly as if it 
were typed at the terminal. 

100 OPEN "DATA.DAT" FOR INPUT AS FILE #1X 

120 INPUT «1X.A.B.C 

125 PRINT A.B.C 

130 CLOSE *rz 

140 END 

To read data from a formatted ASCII file, the INPUT statement that reads 
the data must match the format of the PRINT statement that wrote the 
data. Both statements must contain the same number of data items. (Data 
items in PRINT statements can be constants, variables, or expressions; 
data items in INPUT statements can only be variables.) The two lists of 
data items must contain the same data t 3 rpes, in the same order. The follow¬ 
ing two statements illustrate these rules: 

100 PRINT #rz. NAME*;" ;ACCT25"."5AM0UNT 
300 INPUT *2Xt CUSTOMER*«ACCTN0X»AMT 

The PRINT statement writes data to the file. Be sure to write commas 
between data items in the file if you plan to read the data with INPUT. 
Remember that INPUT treats the data exactly like terminal input. 

The INPUT statement (which may be in a different program) reads data 
from the file. The variable list matches the PRINT statement’s variable list 
in both t 5 T)e and order. Note that if you print data to a file and want to read 
it later in the program, you must close the file and reopen it before you can 
read data from it. 

Each INPUT statement reads data from one record in the file. A record is a 
series of ASCII characters up to a line delimiter (RETURN, FORM FEED, 
LINE FEED, or ESC). It is recommended that you limit the length of each 
record to 132 characters, including line delimiter characters. The INPUT 
statement may not always read longer records correctly. 

Commas separate individual values in a record. If there are more values in 
the record than there are variables in the INPUT statement, BASIC-PLUS 
ignores any extra values (as it does with terminal input). However, if the 
record contains too few values, BASIC—PLUS returns the error "?Not 
enough data in record” (ERR = 59). (This action differs from terminal 
input, where the INPUT statement prompts for additional values.) 

When an INPUT statement encounters a CTRL/Z, BASIC—PLUS returns 
the error **?End of file on device” (ERR = 11). Include an error handling 
routine in your program to process this error. 

You can also read data from a formatted ASCII file with the INPUT LINE 
and MAT INPUT statements. See Sections 15.2.3 and 15.2.4. 


15-14 Formatted ASCII Input and Output 




15.2.2 Opening Your Terminal as an I/O Channel 

There are two ways to open your terminal as an I/O channel in 
BASIC-PLUS: 

1. You can use OPEN and INPUT to open yomr terminal on a nonzero 
channel. For example: 

100 OPEN 'KB:' FOR INPUT AS FILE «2X 
110 INPUT #2Z* A 

BASIC—PLUS does not print a prompting question mark at the termi¬ 
nal. For example: 

100 OPEN 'KB:' FOR INPUT AS FILE *2X 
110 INPUT «2Z. A 
120 PRINT A 
130 END 

When you rim this program, it pauses to let you enter a value for A, but 
does not prompt for the value with a question mark: 

RUNNH 

567.8 

567.8 

Use this method to open your terminal in a special mode. Do not 
include a prompting message in this type of INPUT statement. See 
the RSTS/E Programming Manual for information on special terminal 
operations. 

2. You can use the INPUT statement by itself to access your terminal on 
channel 0. (You cannot specify a channel number of 0 in an OPEN 
statement.) For example: 

10 INPUT «0Z» A$ 

This statement is the same as: 

10 INPUT A$ 

When you specify channel 0, BASICI—PLUS prints the prompting ques¬ 
tion mark. You can include a prompting message in this type of INPUT 
statement. 


15.2.3 INPUT LINE Statement 

The INPUT LINE statement lets you enter a line of data as a single charac¬ 
ter string, regardless of embedded spaces or punctuation. This is different 
from normal string input, where the comma, apostrophe, and single and 
double quotation meirks have special meanings. 
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INPUT LINE has the format: 

INPUT LINE [#<expression>,] <8tring variable> 

For example: 

150 INPUT LINE A$ 

When this statement is executed, the program pauses to let you enter a line 
followed by a RETURN, FORM FEED, LINE FEED, or ESC (see Section 
10.3). You can enter a line up to 132 characters long, including line delim¬ 
iter characters. 

BASIC-PLUS reads every character you tjrpe into the variable A$, includ¬ 
ing quotation marks, commas, and the line delimiter (for example, carriage 
return/line feed). To remove the line delimiter, use the CVT$$ function or 
the LEFT$ function, which are described in Section 10.5. When you input 
CTRL/Z, the system returns the error '7End of file on device” (ERR = 11). 
Include an error handling routine in your program to process this error. 

The INPUT LINE statement can read data from a file as well as from a 
terminal. The following example opens file FZ.DAT on channel 7 and reads 
a string of characters up to the next terminating character: 

100 OPEN 'FZ.DAT' FOR INPUT AS FILE »7X 
110 INPUT LINE nlX, B$ 

To ensure that INPUT LINE reads the string correctly, it is recommended 
that you limit its length to 132 characters, including line delimiter 
characters. 

When reading data from a file, the INPUT LINE statement treats a car¬ 
riage return character (ASCII code 13 decimal) differently depending on 
what character follows it. When the line feed character (AS(3lI code 10 
decimal) follows the carriage return character, these two characters delimit 
(end) the line. The INPUT LINE statement returns a string that ends with 
a carriage return/line feed. 

When a null character (ASCII code 0) follows the carriage return, the 
INPUT LINE statement discards both the carriage return character and 
the null character and continues processing the string. 

When any other ASCII character follows the carriage return character, the 
INPUT LINE statement treats the carriage return character as a normal 
data character instead of a line delimiter. 

15.2.4 MAT INPUT Statement 

The MAT INPUT statement, one of the optional matrix manipulation state¬ 
ments, inputs the values of a matrix from a specified input channel. When 
you do not specify a channel, your terminal is used. For example: 

200 MAT INPUT A<20) 
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Line 200 reads 20 floating-point values as elements of the matrix A. The 
MAT INPUT statement has the form: 

MAT INPUT [#<expre8sion>,] <li8t of matrices> 

BASIC-PLUS reads input from a file or device open on the channel indi¬ 
cated by the expression. 

The following lines open the file DATAl on DM1: on channel 1 (of 12 
possible channels), and read a matrix of values to fill B(10,25): 

laO DIM B(10»25) 

200 OPEN 'DMliDATAl' FDR INPUT AS FILE »1X 
210 MAT INPUT «1Z. B 

The zero elements are not assigned a value. When the input channel is your 
terminal (channel 0), BASIC-PLUS prints a question mark (?). However, 
reference to another channel does not print the prompting character. 
Depending on the naine of the matrix, the MAT INPUT statement allows 
input of floating-point, integer, or string values. 


15.3 Formatted ASCII Examples 

The following programs illustrate formatted ASCII input and output. The 
first program creates a disk file, prompts the user to enter customer names 
and addresses at the terminal, and writes the names and addresses into the 
disk file. The second program reads the data from this disk file and prints it 
on the terminal. 

The first program: 

• Does not supersede an existing file. The program has an error handling 
routine that prompts the user for a new file name if the name entered 
already exists. The program also opens the new file MODE 128%, which 
tells the system not to supersede an existing file. (See the RSTS/E 
Programming Manual for information about MODE values.) 

• Uses INPUT LINE statements to read input from the terminal. Use of 
INPUT LINE lets the program read values that contain embedded com¬ 
mas. The program then uses the CVT$$ function to strip off the line 
terminators that the user types. 

• Writes the data into the file with PRINT statements. Each record in the 
file contains either a customer name, a street address, or a city and state. 

• Prompts the user after each entry to find out if there is more data to be 
entered. The user is prompted to answer "YES” or "NO”. The program 
accepts an answer in either uppercase or lowercase. It uses the CVT$$ 
function to convert whatever the user tjrpes into an uppercase value. 
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ii. 


50 EXTEND 

100 PRINT "Enter name of customer file to be created"? 

110 INPUT LINE CUSNA$ !Get name of file from terminal & 

lUse INPUT LINE in case the name & 
{includes a ppn> which has an & 
{embedded comma 

120 CUSNA$ = CUT$$<CUSNA$ & 

{Strip off line terminators 

125 ON ERROR GOTO 19000 

130 OPEN CUSNA$ FOR OUTPUT AS FILE nlX, MODE 128Z & 

{Open file only if it doesn't & 
{already exist (MODE 128Z) 

200 {Now prompt terminal operator for name and address & 

{information and write it to the name and address file« 

210 PRINT "Enter Customer Name"? 8c 

\ INPUT LINE CUST4NAME$ {Get whole name 8c 

\ CUST*NAME$ = CUT$$ ( CUST . NAME$ ) 8c 

{Strip off line terminators 

220 PRINT "Enter Street Address"? 8c 

\ INPUT LINE CUST«AD0R1$ {Get first address line 8( 

\ CUST*ADDR1^ = CUT$$(CUST*ADDR1$ >450 8c 

{Strip off line terminators 

230 PRINT "Enter City and State"? 8c 

\ INPUT LINE CUST4ADDR2$ {Get second address line 8: 

\ CUST4ADDR2$ = CUT$$(CUST.ADDR2$#4Z) 8c 


{Strip off line terminators 

300 {Now write customer name and address information 8e 
I to the output file* 


310 

320 

330 

400 

410 


420 


430 

440 


PRINT #1Z» 
PRINT nil, 
PRINT #1% 4 
ANYMORE$ = 
PRINT "Any 


CUST4NAME$ 

CUST*ADDR1$ 

CUST4ADDR2$ 

It II 

mo re 


{Print the customer's name 
{Print first line of address 
{Print second line of address 
{Clear answer strins 


and addresses? (Answer YES or NO) 


names 

\INPUT ANYM0RE$ 8c 

{AsK operator if there are any more 
{added to the name and address file 
ANYMORE$ = CUT$$(ANYMORE$ f51 IT.) 8c 
{Conuert lowercase answer to uppercase* 
{spaces and tabs* etc* 

GOTO 200 IF ANYMORE$ = "YES" {Loop bacK if 
IF ANYMORE$ <> "NO" THEN GOTO 410 8c 


customers to be 8c 


remove leadinsT 8c 


mo re 


{If user enters incorrect answer* prompt asain for yes or no 
450 CLOSE «1T {Terminate if no more 

460 GOTO 32767 

19000 {Error handling routine 


19010 IF ERR = IBZ AND ERL = 130 THEN 8c 

PRINT "File already exists - enter a new file name" 8c 
\ RESUME no 8c 

•If file already exists* tell user and retry 
19999 RESUME 0 {Let BASIC-PLUS handle all other errors 
327B7 END 


The next example reads the names and addresses from the customer file 
and prints them on the terminal. The program: 

• Uses INPUT LINE to read the data so that embedded commas are han¬ 
dled properly. 

• Uses PRINT statements to print each record in the file on the terminal. 
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• Contains an error handling routine to process the errors "?Can’t find file 
or account” (ERR = 5) and ”?End of file on device” (ERR = 11). The first 
error occurs when the user enters a file name that does not exist; the 
second error occurs when the INPUT LINE statement encounters a 
CTRL/Z, which marks the end of the file. 

50 EXTEND 

100 PRINT “Enter name of custoiuer file to be printed”? 

110 INPUT LINE CySNA$ !Get name of file from terminal & 

!Use INPUT LINE in case name & 

Icontains embedded comma 
120 CUSNA$ = CUT$$(CUSNA$fax) & 

‘Strip off line terminators 

130 ON ERROR GOTO 19000 

140 OPEN CUSNA$ FOR INPUT AS FILE #2Z & 

lOpen file if it already exists Be 
!Use default REC0RDSI2E 

150 !Now read name and address of one customer? Be 

‘which is stored in three records? one for name? Be 
‘one for street address? and one for city and state* Be 
!Use INPUT LINE so embedded commas are handled properly* 

160 INPUT LINE nTl f CUST*NAME$ Be 

\ CUST*NAME$ = COT$$(CUST*NAME$ ?4Z) Be 
.‘Read name and strip off line terminators 
170 INPUT LINE #27.? CUST*ADDR1$ Be 

\ CUST*ADDR1$ = C‘*‘T$$(CUST* ADDR1$ ?47) Be 
IRead street address and strip off line terminators 
180 INPUT LINE #27? CUST*ADDR2$ Be 

\ CUST*ADDR2$ = CUT$$ ( GUST * ADDR2$ ?47) Be 
IRead city and state and strip off line terminators 
190 PRINT CUST*NAME$ Be 

\ PRINT CUST*ADDR1$ Be 
\ PRINT CUST*ADDR2$ Be 

\ PRINT IPrint name? address? and a blanK line 

200 GOTO 160 ILoop bacK and read next name and address 

19000 IF ERR = 57 AND ERL = 140 THEN Be 

PRINT “The file name you entered does not exist*" Be 
\ RESUME 100 Be 

Ilf file does not exist? tell user and reprompt for file name* 
19010 IF ERR = 117 AND ERL = 160 THEN Be 
PRINT "Processin!^ is complete" Be 
\ CLOSE #27 Be 
\ RESUME 32767 Be 

lEnd of file reached on input? print completion message? Be 
Iclose file? and end program* 

19999 RESUME 0 ILet BASIC-PLUS handle all other errors 

32767 END 
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Chapter 16 
Virtual Arrays 


Many applications require you to address and update individual records on 
a disk file in a random manner. Other applications require more room for 
storing arrays than is economical in main memory. BASIC-PLUS fills both 
requirements with a random access file system called virtual arrays. 

A virtual array is a data array that is stored in a disk file. By using virtual 
arrays, you can: 

• Store arrays in a permanent form 

• Operate on arrays that are too large to fit in memory 

One virtual array file can contain several data arrays. 

To use virtual arrays, you combine the programming techniques for mem¬ 
ory arrays with the programming techniques for file access. For example, to 
set up a virtual array, you use a special form of the DIM statement to 
dimension the array, and you open a file. You can then reference any ele¬ 
ment of one or more arrays in the file the same way you reference memory 
arrays. No explicit I/O statements are needed. BASIC-PLUS automati¬ 
cally reads data from the file into the I/O buffer, transfers data between 
the buffer and your program, and writes data from the buffer to the file. 
When you finish using a virtual array, you close the file. 

While virtual arrays are similar to memory arrays, they are not identical. 
Unlike memory arrays, for example, virtual array elements are not set to 0 
when your program starts executing. Instead, when you open a virtual 
array file, elements have whatever value happens to be on the disk. You 
must initialize the array in your program. String handling also differs in 
memory eirrays and virtual arrays. 
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Because virtual arrays are disk files, the order in which you reference 
array elements can significantly affect execution time. BASIC-PLUS reads 
portions of the array from disk into the I/O buffer in response to references 
in your program. This chapter describes how virtual arrays are stored and 
explains how to reference array elements with a minimum number of disk 
accesses. 

16.1 Virtual Array DIM Statement 

To have a matrix of data in a virtual array, you must declare it in a special 
form of the DIM statement. This special DIM statement is: 

DIM #<integer constant>, <li8t> 

The integer constant is between 1 and 12. This integer constant corre¬ 
sponds to the channel number where the program has opened a disk file. 
The variable list appears as it would in a DIM statement for an array in 
main memory. Thus, a lOO-by-100 array of floating-point numbers is 
defined as: 

100 DIM #12Z. A(100»100) 

You can store floating-point constants, integer constants, and strings in 
virtual array matrices. You can also specify more than one matrix in a 
virtual array file. For example: 

250 DIM A(1000)» BZ(2000)» C$(2500) 

Line 250 allocates space for 1001 floating-point numbers, 2001 integer 
numbers, and 2501 16-character strings (note that space for the 0th ele¬ 
ment is included for each matrix). However, if you define a virtual array in 
this fashion, you should dimension the arrays to the same size with future 
references. 

16.2 Virtual Array String Storage 

String data is handled differently in virtual arrays than in memory arrays. 
In memory eirrays, you do not specify string length. Instead, it varies 
dynamically between 0 and 32767 characters. In virtual arrays, however, 
strings have a fixed maximum length. The maximum length must be one of 
the following powers of 2: 

2, 4, 8, 16, 32, 64, 128, 256, 512 

You specify the maximum length for virtual array strings in the DIM state¬ 
ment. Use the form: 

DIM #<integer con8tant>,<8tringvar(dimension(s))>[= <con8tant>] 

For example: 

150 DIM #1Z» A$(100> = 32Xf B$(100) = AZ» C*(100) 
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This statement dimensions a virtual array file that contains three string 
arrays: 

A$ Consists of 101 strings of 32 characters each, maxim nnn 
B$ Consists of 101 strings of 4 characters each, mayimnnn . 

C$ Consists of 101 strings of 16 characters each, maximum. 

Each element in a string array has the same maximum length. 

Although elements can be shorter than the maximum length, 
BASIC-PLUS reserves space in the file for each element to be the maxi¬ 
mum length. If you do not specify a maximum length, BASIC-PLUS 
assumes a default length of 16 characters. 

If you specify a length that is not a power of 2, BASIC-PLUS uses the next 
higher size. For example, these two statements have the same result: 

100 DIM X$(10) = 65 

100 DIM *1Z, X$<10) = 128 

Both statements set the maximum string length of X$ to 128 characters. 

In addition to string length, BASIC-PLUS also handles trailing null 
characters differently in memory arrays and virtual arrays. BASIC-PLUS 
retains trailing nulls for strings in memory, but drops them when accessing 
string data in virtual arrays. (See Section 16.4.1 for more information.) 

16.3 Opening and Closing a Virtual Array File 

To reference your virtual array file, you must first associate a disk file 
name with a channel number from 1 to 12. (You must also use this same 
channel number in the virtual DIM declaration.) Do this with an OPEN, 
OPEN FOR INPUT, or OPEN FOR OUTPUT statement: 

OPEN <string> ^|pQ^ OinPOTjj <expression> 

The string is the disk file name and the expression specifies the channel 
number. (This format is described in Section 14.5.) For example: 

350 OPEN 'ACCT.DAT' AS FILE •IX 

This statement associates the file named ACCT.DAT with I/O channel 1. If 
ACCT.DAT exists, the system uses the existing file. If there is no file 
named ACCT.DAT, the system creates one. If you wish to destroy a file 
named ACCT.DAT and create a file of the same name, you can use the 
statement: 

350 OPEN 'ACCT.DAT' FOR OUTPUT AS FILE *12 
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This statement deletes the existing file and creates a new one. If you want 
the system to alert you that the file ACCT.DAT is not present, type: 

350 OPEN 'ACCT.DAT' FOR INPUT AS FILE «U 

The system returns an error message if ACCT.DAT is not found: 

?Can't find file or account at line 350 

BASIC-PLUS does not initialize virtual arrays when you open them. Thus, 
each element contains whatever value happened to be on the disk when the 
file was created. For this reason, immediately after creating a virtual 
array, you should: 

1. Set all elements of numeric arrays to zero 

2. Set all elements of string arrays to the null string (" ") 

Virtual arrays permit internal buffers larger than 512 characters. There¬ 
fore, you can use the RECORDSIZE option when opening a virtual array 
file. If specified, the RECORDSIZE must be one of the following powers 
of 2: 512, 1024, 2048, 4096, 8192, or 16384. 

16.3.1 Preextending a Virtual Array 

The system overhead for extending a file by one data element or by many 
elements is nearly the same. Thus, it is more efficient to immediately 
extend a new file to its final length than to extend it many times. When¬ 
ever you know the maximum size of a file, you should extend it to its full 
size. For example: 

100 DIM A(IOOOOX) 

110 OPEN 'DATA' FOR OUTPUT AS FILE «1Z 

120 A(10000Z)=0 

This example extends the virtual array A to its final length. However, 
BASIC-PLUS does not initially zero virtual arrays. In the previous exam¬ 
ple, A(0) through A(9999) contain indeterminate values. Unless you are 
careful, these values could cause a program failure. You should first zero 
the virtual array as follows: 

300 A(IZ)= 0.0 FOR IZ = lOOOOZ TO OZ STEP-IZ 

This statement immediately extends the file to its final size and then zeros 
it sequentially. The following statement performs the same function but is 
less efficient: 

300 A(1Z>= 0.0 FOR IZ = OZ TO lOOOOZ 

This statement extends the file each time it requires another disk block. 
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16.3.2 Closing a Virtual Array File 

The CLOSE statement terminates I/O between the BASIC-PLUS program 
and the virtual array. Once you close a virtual array, you can reopen it for 
reading or writing on any channel. 

You must close virtual arrays before the end of program execution. A 
CLOSE statement with a positive channel munber outputs the last buffer of 
data elements to the virtual array file. A CHAIN statement or a CLOSE 
with a negative channel number automatically closes open virtual arrays 
but does not output the contents of the I/O buffer to the array. The format 
of the CLOSE statement is: 

CLOSE [#] <expression> [,[#] <expression> ,...] 

The expression has the same value as the expression in the OPEN state¬ 
ment. It indicates the channel number of the array to close. You can close 
any number of arrays with a single CLOSE statement. To close more than 
one array, separate the expressions with commas. For example: 

255 CLOSE 

345 CLOSE •lOX 

435 CLOSE «-5Z 

Line 255 closes the virtual arrays opened on channels 2 and 4. Line 345 

closes the array open on channel 10. Line 495 closes channel 5 without 
writing the I/O buffer to the disk file. 

16.4 Virtual Array Programming Conventions 

When you use virtual arrays, you can encounter recoverable errors if your 
program does any of the following: 

• References a virtual array without first opening the file 

• References a nondisk file (for example, a magnetic tape file or a line 
printer) as a virtual array 

• Defines an array bigger than the available disk storage on the system 

Remember that you must close a virtual enray file before stopping the 
program or chaining to another program. 

16.4.1 Virtual Array Storage 

Any data element in a virtual array is contained in a single block 
(512 bytes) of disk storage. This restriction has no effect on integers and 
floating-point items, where the size of data items is fixed. However, it lim¬ 
its the maximum length of a virtual array string element to 512 characters. 
The number of data elements stored in each disk block depends on the size 
of each element. 


Virtual Arrays 16-5 






The number of elements in virtual strings depends on the maximiun string 
length you specify in the DIM# statement. The size of a virtual string 
defaults to 16 characters; you can specify 2, 4, 8,16, 32, 64,128, 256, or 512 
characters. Table 16-1 indicates the number of array elements stored in 
each block of a virtual array file. 


Table 16-1: Virtual Array Storage 


Data Type 

Number of Elements 
per Block 

Integer (%) 

256 

Two-Word Floating-Point 

128 

Four-Word Floating-Point 

64 

String ($) 

512/N 

(N equals the maximum length) 



Strings in virtual arrays occupy preallocated space in the virtual file. They 
differ fix)m strings in memory, where space is allocated dynamically. A disk 
block containing virtual strings can be considered to be a succession of 
fields, each having the maximum string length. 

When a virtual string is assigned a new value, it is stored left-justified in 
the appropriate field. If the new string value is shorter than the m ax imum 
length, the remainder of the field is filled with trailing null characters. 
When the string is retrieved, its length is computed as the maximum string 
length minus the number of trailing null characters. 

16.4.2 Translation of Array Subscripts into File Addresses 

When you reference a virtual array element, BASIC-PLUS translates 
it into a file address. To translate an array subscript into a file address, 
BASIC-PLUS computes the relative distance from the specified item to the 
first item in the array. Then it adds the relative distance from the first 
element of the array to the first item in the file. The first quantity is 
computed from the array subscript and the number of elements per block, 
as shown in Table 16-1. The second number is a constant for each array 
in a file and is computed from the parameters specified in the DIM# 
statement. 

Since the DIM# statement contains the only information used to define the 
structure of a file, you can specify different accessing arrangements for the 
same file in one or more programs. For example, you can reference the 
same data as either a series of 32-byte strings (A2$) or 16-bjfte strings 


(Al$): 







10 

DIM 

#1X »A1$<1001) 

= IB 

\ 16 

CHARACTER 

STRINGS 

20 

DIM 

#n»A2$(500) = 

32 

!32 

CHARACTER 

STRINGS 

30 

OPEN 

'FIL1.DAT' AS 

FILE ^ 1 % 


lOIRTUAL 

ARRAY FILE 


Remember, in BASIC—PLUS array subscripts begin with 0 and not 1. An 
array with dimension n or (n,m) contains n -f-1 or [(n -f- l)*(m +1)] elements. 
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Your program can define two-dimensional virtual arrays as well as one¬ 
dimensional virtual arrays. Two-dimensional arrays are stored linearly, 
row-by-row, on disk and in memory. Thus, in the case of an array X(l,2), 
the array appears logically as follows: 


X(O.O) 

X(0,1) 

X(0,2) 

X(1.0) 

X(1,1) 

X(1,2) 


Physically this array is stored as follows: 


Lowest Address 


Highest Address 



When you reference a virtual array sequentially, it is more efficient to 
reference the rows, rather than the columns, in sequence. For example. 
Program 1 computes the sum of each row and column in a two-dimensional 
array far more efficiently than Program 2. 

Program 1 

LISTNH 

too REM - PROGRAM 'ONE' TO COMPUTE SUMS EFFICIENTLY & 

'ARRAY' CONTAINS VIRTUAL ARRAY & 


no 

R(IX) IS SUM OF ROW I & 
C(JX) IS SUM OF COLUMN J 
DIM #1X ♦AClOX#50X> & 


120 

! 10 ROWSf 50 COLUMNS 

DIM R(lOX) ♦ C<50X> fic 


130 

□PEN 'ARRAY' FOR INPUT AS FILE #1X 

&C 


! OPEN VIRTUAL,FILE AND INITIALIZE 

SUMS 

lao 

MAT R = 2ER & 


150 

\ MAT C = ZER 

FOR IX = IX TO lOX & 


160 

! OPERATE ROW-BY-ROW 

FOR JX = IX TO SOX & 


170 

! DO EACH COLUMN IN ROW 

R(IX> = R(IX) + A(IXfJX) &C 


180 

! TOTAL ACROSS ROW 

C(JX> = C(JX) + A<IX#JX) &C 


190 

! TOTAL DOWN COLUMN 

NEXT JX & 


200 

\ NEXT IX & 

1 COLUMN SUM IS INSIDE LOOP 

MAT PRINT R; & 



\ MAT PRINT Ct & 

! PRINT ROW TOTALS. THEN COLUMN TOTALS 

210 

CLOSE nlX 


32767 

END 



Ready 
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Program 2 


LISTNH 

100 REM - PROGRAM 'TWO' USES VIRTUAL MEMORY INEFFICIENTLY 
110 DIM #1Z fA( lOX tSO^C) & 

I 10 ROWSf 50 COLUMNS 
120 DIM R(lOZ)# C<50Z) & 

130 OPEN 'ARRAY' FOR INPUT AS FILE «1X & 

! OPEN VIRTUAL FILE AND INITIALIZE SUMS WITH MAT 
140 MAT R = ZER & 

\ MAT C = ZER 

150 FOR JZ = IZ TO 50Z & 

! OPERATE ONE COLUMN AT A TIME 
160 FOR IZ = IZ TO lOZ & 

I AND ACROSS ROW 

170 R(IZ) = R(IZ) + A(IZfJZ) & 

! TOTAL ACROSS ROW 
180 C(JZ) = C(JZ) + A(IZ#JZ) 8c 
! TOTAL DOWN COLUMN 
180 NEXT IZ 8c 
\ NEXT JZ 

200 MAT PRINT R; 8c 

\ MAT PRINT C; 8: 

! PRINT ROW TOTALS# THEN COLUMN TOTALS 
210 CLOSE #1Z 
32767 END 


Ready 


In virtual arrays, two or more arrays can share the same file. For example, 
the following DIM# statement is legal: 

100 DIM #1Z»A(1000) »BZ(999) fCdOOO) 


Array B% begins immediately after element 1000 of A and array C begins 
immediately after B%(999). The disk layout is shown in Figure 16-1. 

Figure 16-1; Virtual Array File Layout 


A(0) 

A(1) 

* , * 

A(999) 

A(1000) 

B%(0) 

B%(1) 

^ 0 

^ 4 

B(998) 

B(999) 

C(0) 

C(1) 

4 0 

^ ^ 4 

C(999) 

C(1000) 
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Because arrays are stored sequentially on disk, you should not set up logi¬ 
cal records that consist of matching elements of different arrays. The fol¬ 
lowing example, which prints a mailing list, shows an inefficient use of 
multiple arrays in a virtual array file: 


100 DIM FIRST.NAME$( lOOZ) * LAST . NAME* (lOOZ ) >8. 

ADDRESS*(lOOZ) = SAX 

150 OPEN "MAIL.VIR" FOR INPUT AS FILE #1Z 
200 FOR IZ = IZ TO lOOZ 

210 PRINT FIRST.NAME(IZ) " 5LAST . NAME* (IZ ) 

220 PRINT ADDRESS*(IZ) 

230 PRINT IBlank line 
2A0 NEXT IZ 
250 CLOSE «1Z 
32767 END 


In this example, several disk accesses are needed to print each individual’s 
name and address. 


The following program uses a single array element as a logical record. This 
program is more efficient than the first one because only one disk access is 
needed to print each individual’s name and address. 


100 DIM «1X. CUST0MER*(lOOZ) = 128Z 

150 OPEN "MAIL.OIR" FOR INPUT AS FILE «1X 

200 FOR IZ = IZ TO lOOX 

210 PRINT LEFT(CUSTOMER*(IZ),16Z);" & 

PRINT MID(CUSTOMER*(IX)»1BZ»16Z) 

220 PRINT MID(CUSTOMER*(IX)#33ZfSaZ) 

230 PRINT IBlank line 
2a0 NEXT IZ 
250 CLOSE «1Z 
32787 END 


For string arrays in virtual array files, you should specify the maximum 
length of the longest element of that array. This is because BASIC—PLUS 
allocates a fixed number of b 5 rtes in the disk file to elements in string 
arrays (see Section 16.2). 

A single string element never crosses a disk block boundary, where each 
disk block contains 512 bytes or 256 words. For example: 

100 DIM «*1Z»AZ<2) »B*(1000)=A 

BASIC—PLUS allocates the first three words of the disk block to A%. If 
array B$ were to begin immediately after A%, one of the elements of B$ 
would cross a block boimdaiy. Hence, B$ begins at the start of the second 
block in the file rather than immediately after A%. 

When you assign more than one array to a single virtual array file, each 
array begdus immediately after the last element of the preceding array. 
This occurs unless such an allocation splits an element of the array across 
two disk blocks. To avoid this split, the array begins at the start of the next 
block of the file. The remaining words in the first block are not used. 
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16.4.3 Access to Data in Virtual Arrays 

Only a portion of a virtual array is in memory at once. BASIC-PLUS trans¬ 
fers this data directly between the disk and an I/O buffer in your area. 
BASIC-PLUS creates the I/O buffer when you execute the OPEN state¬ 
ment. This buffer must be a multiple of 512 bytes (one block) long; you may 
specify it as several blocks with the RECORDSIZE option in the OPEN 
statement. For each virtual array file, BASIC-PLUS notes: 

1. Which block of the file is in the buffer 

2. Whether the data in the buffer has been modified since it was read into 
memory 

After BASIC-PLUS translates a virtual array address into a file address, it 
checks whether the block containing the referenced item is in the buffer. If 
the necessary block is present, the reference proceeds; if not, BASIC-PLUS 
reads another portion of the file into the buffer. If you alter the current data 
in the buffer, BASIC—PLUS rewrites this data on the disk before reading 
new data into the buffer. 

BASIC-PLUS ultimately locates all references to virtual arrays by using 
file addresses relative to the start of the file. No symbolic information con¬ 
cerning array names, dimensions, or data ts^ies is stored in the file. Thus, 
different programs can use different array names to refer to the data in a 
single virtual array file. Be cautious in such operations; it is your responsi¬ 
bility to ensure that programs referencing a set of virtual arrays are 
referencing the same data. For example: 

Program 1 contains: 

100 !PROGRAM ONE 

110 DIM #1% f X(10> » Y(10) 

120 OPEN 'FILE.DAT' AS FILE ^IX 


Program 2 contains: 

100 !PROGRAM TWO 

110 DIM *1X » 2(10) » X(10) 

120 OPEN 'FILE.DAT' AS FILE «1X 

Whenever Program 2 references array Z, it uses the data known to 
Program 1 as array X. Both X and Z are the first arrays in their declara¬ 
tions, both contain floating-point data, and both are 11 elements 
(X(0),...,X(10)) long. These two arrays, then, correspond in position, type, 
and dimension. 

References to the array X in I^rogram 1 and to the array X in Program 2 do 
not refer to the same data, even though both use the virtual file FILE.DAT. 
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Note also that the two statements in Example 1 are not equivalent to the 
statement in Example 2: 


Example 1 Example 2 

100 DIM »H%*A(102:) 100 DIM «1Z >A< 10%) r B(10%) 

no DIM *1% »B( 10%) 


In Example 1, the arrays A and B equal each other; they constitute the first 
array in the file open on channel 1. In Example 2, both arrays A and B exist 
in separate areas in the file open on channel 1, 

Be careful not to open a file under two channel numbers. For example: 

150 OPEN 'VALUES' AS FILE «1% & 

\0PEN 'VALUES' AS FILE «2% 


200 DIM #1%» X$(20%) 

210 DIM *2%» Y$<20%) 

This example creates two buffers for the storage of channel 1 and channel 2 
I/O. If you change the same block of the file in both buffers, the system 
adds the changes from only one of the buffers to the file. The system may 
overwrite the buffer you wrote first with the other buffer. Consequently, 
any data change in the first buffer is lost. 

If you attempt to write on file #2, you get a "?Protection violation” error, 
imless the file is open in update mode (see the RSTS/E Programming 
Manual). In either case, the write is unsuccessful. 

16.4.4 Allocating Disk Storage to Virtual Array Files 

The dimensions in a DIM# statement set maximum values for subscripts. 
They do not compute the initial size of the virtual array file allocated on 
disk. Instead, the system creates the file with a length of zero blocks and 
appends blocks to the file for the highest file address referenced in the 
array. 

You can thus specify array dimensions larger than required when you write 
a program. Such programs can operate on larger arrays without modifica¬ 
tion and without tying up disk storage. The only place you find areas of 
unallocated disk storage is at the end of the file. 

As you append blocks to a file, the system does not initialize their contents 
to zero. The data previously recorded in a block is available to the new 
owner of the block. If your files contain confidential information, you 
should overwrite the data before deleting the file. 

To override the dynamic virtual array allocation, you can reference the last 
element in the virtual array file. This preallocates all blocks in the file. As 
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noted earlier, the contents of these blocks appended to the file are 
unknown. Use a FOR loop or the MAT ZER statement to initialize array 
values to a known (zero) quantity. 

16.4.5 Simultaneous Access of a Virtual Array 

The system gives write privileges only to the first program to open a file 
(array). When a second program attempts to modify an open array, the 
system reads the appropriate block from the disk but changes it only in the 
second program’s buffer—^not on the disk. When the second program refer¬ 
ences this array and attempts to read another block from the disk, a 
’^Ih'otection violation” error occurs. This error occurs because the system 
attempts to update the disk with the information in the current block 
before the required block is read into memory. 

Because the second program has no write privileges, it cannot update 
the disk. A CLOSE operation at this point also results in a ”?Protection 
violation” error for the same reason. Once the job returns to BASIC-PLUS 
command level and you execute a NEW, OLD, or RUN command, the sys¬ 
tem performs a CLOSE on all channels. In this case, no write is attempted, 
so the CLOSE is successful. 

To avoid simultaneous write accessing of a virtual array, determine 
whether yovu* program has write privileges. Do this by testing the STATUS 
veiriable (see Section 17.1.1): 

100 OPEN 'ARRAY' AS FILE 

no IF (STATUS AND 1024%) 8. 

THEN PRINT 'NO WRITE ALLOWED ON ARRAY' 8, 

\ STOP 

Do not use MODE 1% to open virtual array files. (MODE 1% allows you to 
open a file for simultaneous update by more than one program; see the 
RSTS/E Programming Manual for more information.) Your buffer is modi¬ 
fied when you open an array with the MODE 1% option; thus, the system 
does not update the disk at this time. 

Even when the first of several programs unlocks the file, allowing other 
programs to access the array, its modifications exist only in the first user’s 
buffer. The system updates the array only when the first user accesses data 
from another block. 

16.5 Programming Examples 

As an example of virtual array usage, consider the problem of generating a 
large array of random numbers. Since a physical disk block is 256 words, 
an efficient array would contain a multiple of 256 elements. The following 
example uses a virtual array file, ARRAY1.DAT, that contains 5120 data 
elements in a 2-by—2560 array. Twenty physical blocks store this array. 
The program creates the virtual array V% by assigning a random value 
between 0 and 999 to each element in the array. 
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LISTNH 

1000 

DIM #3Xf VX<IX*2559X) 

1010 

OPEN 'ARRAYKDAT' 

AS FILE #3X 

1020 

FOR IX = OX TO IX 


1030 

VX(IX#JX) = RND * 

lOOOX FOR JX 

1040 

NEXT IX 


1050 

CLOSE #3X 


32767 

END 


Ready 




After the file AURAYl.DAT is created, you can access the virtual array 
elements by their subscripts. The next program prints every 256th value. 
Note that the array format in the DIM statement must be identical to the 
original format for predictable results. The file’s channel number and the 
array’s name can change, but the array must be formatted the same way 
every time it is accessed. 


ESTNH 

1000 DIM max, X2(1I»2559Z) 

1010 OPEN 'ARRAY1.DAT' AS FILE #411; 

1020 FOR IX - OX TO IX 

1030 PRINT XX<IX.JX); FOR JX=0X TO 2559X STEP 25BX 

1040 NEXT IX 

1050 CLOSE #4X 

lOBO PRINT 

327B7 END 

Ready 

RUNNH 

204 909 954 839 B5 131 537 784 371 798 565 173 122 910 39 8 318 
468 958 289 


Ready 


You can change values of array elements with the assignment statements 
LET, INPUT, or READ. This program changes the value of specified data 
elements: 


LISTNH 

1000 DIM MZ(lZf2559Z) 

1010 OPEN 'ARRAY1.DAT' AS FILE n3% 

1015 ON ERROR GOTO 1050 

1020 INPUT 'ENTER THE I AND J LOCATION OF THE ELEMENT'; llfJX 
1030 NX = VX(IXtJX) 

1040 INPUT 'ENTER THE NEW OALUE' ; UXdX^JX) 

1045 PRINT fic 

\ PRINT 'OLD VALUE WAS: ' ;NX# ' NEW VALUE IS: '5VX(IXfJX> & 
\ PRINT & 

\ GO TO 1020 
1050 CLOSE #3X 
32767 END 
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RUNNH 
ENTER THE 
ENTER THE 

OLD VALUE 

ENTER THE 
ENTER THE 

OLD VALUE 

ENTER THE 
ENTER THE 

OLD VALUE 

ENTER THE 


I AND J LOCATION OF THE ELEMENT? 0.9 
NEM VALUE? BOO 

MAS: 678 NEM VALUE IS: 600 

I AND J LOCATION OF THE ELEMENT? 1.255 
NEM VALUE? 333 

HAS: 937 NEM VALUE IS: 333 

I AND J LOCATION OF THE ELEMENT? 0.2225 
NEM VALUE? 9999 

HAS: 424 NEM VALUE IS: 9999 

I AND J LOCATION OF THE ELEMENT? 9.9 


Ready 


The leist two exsunples compare different access methods for virtual arrays. 
Tn the previous examples, ARRAY1.DAT was allocated as follows: 


Block 1 V(0,0) - V(0,255) 

Block 2 V(0.256) - V(0,511) 

Block 3 V(0,512) - V(0,767) 


Block 10 V(0,2304) - V(0.2559) 

Block 11 V(1,0) -V(1,255) 


Block 20 V(1,2304) - V(1,2559) 


Notice that the second subscript varies from 0 to 2559 for each of the two 
values (0 and 1) of the first subscript. The system transfers a physical 
record (that is, a block) from the disk to memory at one time. Therefore, the 
system performs only one disk access for each group of 256 consecutive data 
elements; for example, V(0,256)—V(0,511). It is more efficient to sequen¬ 
tially access data elements in one block than to access data elements in 
different blocks. 

The following two programs access, but do not print, each element in the 
virtual array. The first access method transfers a new block to memory for 
each data element accessed, resulting in 5120 disk accesses. The second 
method, however, transfers a new block to memory only once per 256 data 
elements, resulting in 20 disk accesses. The difference in execution time 
between both methods is significant. 
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Program 1 
(Inefficient) 

LISTNH 

1000 DIM n3Xf MZ(1X#25591) 

1010 OPEN 'ARRAYKDAT' AS FILE #3X 
1015 T = TIME(O) 

1020 FOR JX = OX TO 2559X 

1030 DX = VX(IX#JX) FOR IX = OX TO IX 

1040 NEXT JX 

1045 PRINT 'THIS ACCESS TOOK ';TIME(0) - Ti'SECONDS.' 

1050 CLOSE «3X 
327G7 END 

Ready 

RUNNH 

THIS ACCESS TOOK 422 SECONDS. 

Ready 

Program 2 
(Efficient) 

LISTNH 

1000 DIM USX# 0X(1X#2559X) 

1000 OPEN 'ARRAY1.DAT' AS FILE «3X 
1015 T TIME<0) 

1020 FOR IX * OX TO IX 

1030 DX = MXdXfJX) FOR JX = OX TO 2559X 
1040 NEXT IX 

1045 PRINT 'THE SECOND ACCESS TOOK'iTIME(0) - T 'iSECONDS.' 
1050 CLOSE «3X 
32767 END 

Ready 

RUNNH 

THE SECOND ACCESS TOOK 2 SECONDS. 

Ready 
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Chapter 17 
Block I/O 


The I/O methods described so far are easy to use and flexible enough for 
many applications. But each method has its limits. Formatted ASCII I/O 
does not allow random access to data. In addition, formatted ASCII process¬ 
ing consumes CPU time as it scans for record delimiters and converts 
numeric data to and from ASCII format. Virtual arrays provide random 
access to files, but the files can be stored only on disks. 

Block I/O, the third I/O method in BASIC-PLUS, does not have the limits 
of formatted ASCII or virtual arrays. Instead of performing I/O operations 
for you in a predefined way, BASIC-PLUS gives you access to the basic I/O 
services of the RSTS/E operating system. You can perform any type of 
physical I/O available under RSTS/E. 

In block I/O, you control both the physical movement of data and the logi¬ 
cal meaning of data. You can write programs that perform either or both 
types of operations using block I/O techniques. 

In block I/O, your program directly controls the transfer of data between a 
device and its I/O buffer in your program area. You deal with a block I/O 
file as a series of physical records. Each physical record corresponds to one 
block on the storage device; the size of the block depends on the device you 
are using. In a disk file, each block has a number associated with it. This 
number gives you random access to each block in the file. 

Because you deal with physical records in block I/O, you can tailor a 
program to the characteristics of a particular device. You can also take 
advantage of operating system features such as file sharing and multi¬ 
terminal I/O. Most of the device-dependent progr a m mi ng techniques 
described in the RSTS/E Programming Manual are available to 
BASIC-PLUS programmers only through block I/O. 
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Besides controlling the transfer of data between the device and the I/O 
buffer, you also have to make data in the buffer meEiningful to the rest of 
your program. In all types of BASIC-PLUS 1 10, data in the I/O buffer is in 
unformatted binary form, just as it is on the storage device. In formatted 
ASCII and virtual array I/O, BASIC-PLUS automatically processes the 
data in the buffer and makes it available to your program as string, inte¬ 
ger, or floating-point data. In block I/O, however, BASIC-PLUS does not 
process the data in the buffer. Instead, it provides you with a set of tools for 
processing the data yourself. You can read and write any file format using 
these tools. 


Block I/O is the most powerfiil I/O method available in BASIC-PLUS. But 
it is also the most difficult to method to use because your program has to do 
most of the work that BASIC-PLUS does for you in formatted ASCII and 
virtual array I/O. You will need to learn several new programming tech¬ 
niques to use block I/O. 

This chapter describes the statements and functions BASIC—PLUS provides 
for doing block I/O. The first part of the chapter describes the GET and 
PUT statements, which perform physical I/O. GET and PUT read and 
write blocks of data between a device and its I/O buffer. These statements 
have options that let you read and write specific blocks in a disk file. 


The next part of the chapter describes the tools for making the data in the 
I/O buffer meaningful to your program: 


FIELD statement Lets you access the I/O buffer as string 

data by mapping string variables to bviffer 
locations. 

LSET and RSET statements Move string values from your program into 

these buffer locations. 

CVT conversion functions Let you convert data from string to integer 

or floating-point format (and back) as you 
transfer it between the I/O buffer and your 
program. 


This chapter also describes other BASIC-PLUS features that are often used 
with block I/O: 


RECOUNT variable 
STATUS variable 


BUFSIZ function 
SWAP% function 


Contains the number of characters read 
after an input operation. 

Contains information about the device you 
last opened. 

Returns the buffer si^ of an open channel. 

Swaps the low and high order bytes of an 
integer. 
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17.1 Opening a Block I/O File 

As with all data files, you must open a file before executing block I/O 
statements on it. The format of an OPEN statement is: 

OPEN <8tring>|^j^^®^JJJ^jjASFILE [#] <expres8ion> 

[.RECORDSIZE <exp> ] [.CLUSTERSIZE <exp> ] [.FILESIZE <exp> ] [.MODE <exp> ] 

The OPEN statement opens an I/O channel and establishes an I/O buffer. 
See Chapter 14 of this manual for a description of the OPEN statement. 
The RSTS /E Ptvgramming Manual contains additional information about 
OPEN statement options. The rest of this section introduces the STATUS 
variable and the BUFSIZ function, which you use with the OPEN 
statement. 

The STATUS variable and the BUFSIZ function return information about 
an open I/O channel. These tools are useful when you open a file without 
knowing anything about it. For example, if you are writing a general- 
purpose program, you may want to prompt the user for a file or device to 
open. 

In this kind of program, you do not know in advance what the user will 
specify. You can use STATUS and BUFSIZ to get information about the file 
or device after you open it. 

17.1.1 STATUS Variable 

The STATUS variable contains information about the last channel on 
which your program executed an OPEN statement. The variable is a 16-bit 
word, each bit of which your program can test to determine status (see 
Section 11.7.4.1 for an example of bit testing). Table 17-1 shows the infor¬ 
mation, the tests, and the meaning of each bit. Note that the STATUS 
variable returns RSTS-specific information. 


17.1.2 BUFSIZ Function 

In certain applications, it is important for a program to determine the 
buffer size of an open channel. This is especially true if the OPEN state¬ 
ment specifies a logical device name. You can use the integer function 
BUFSIZ to extract this information. 

The BUFSIZ function returns the size of the buffer for a specified open 
channel as an integer. For example: 

20 YZ* BUFSIZ(NZ) 

This statement returns to Y% the size of the buffer in number of bytes for 
channel N%. If the channel is closed, the fimction returns 0. 
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Table 17-1: STATUS Variable 


Bit 

Test 

Meaning 

0-7 

(STATUS AND 255%) 

The first eight bits of the word contain the han¬ 
dler index. The following values apply for vari¬ 
ous devices. 



0 Disk 

2 Terminal 

4 DECtape 

6 Line Printer 

8 Paper Tape 

Reader 

10 Paper Tape 

Punch 

12 Card Reader 

14 Magnetic tape 

16 PK: device 

(pseudo keyboard) 

20 RJ: device 

(2780 remote job 
entry) 

22 NL: null device 

24 DMCll/DMRll/ 
DDCMP Interface 

26 Auto-Dialer 

28 X-Y Plotter 

30 TU58 DECtape U 

32 KMCll 

34 IBM Interconnect 

38 DMPll/DMVll 



18 DX: device 
flexible diskette 


8 

(STATUS AND 256%)<>0% 

The device is open for non-file-structured pro¬ 
cessing or is a non-file-structured device. 

9 

(STATUS AND 512%)<>0% 

The job does not have read access to the device. 

10 

(STATUS AND 1024%)<>0% 

The job does not have write access to the device. 

11 

(STATUS AND 2048%)<>0% 

The device maintains its own horizontal posi¬ 
tion. Such devices are keyboards and line 
printers. 

12 

(STATUS AND 4096%)<>0% 

The device accepts modifiers. Such devices use 
the record number as a modifier word rather 
than a physical position of the device. Key¬ 
boards, line printers, and card readers are such 
devices. 

13 

(STATUS AND 8192%)<>0% 

Device is a character device. 

14 

(STATUS AND 16384%)<>0% 

Device is an interactive device (keyboard). 

15 

(STATUS <0%) 

Device is a random access blocked device, such 
as disk and non-file-structured DECtape. 






17.2 Closing a Block I/O File 

The CLOSE statement (described in Section 14.6) closes open I/O channels. 
It has the form: 

CLOSE [#] <expression> [,[#] <expre88ion> ,...] 


The value of each expression specifies one of the 12 I/O channels. 
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Unlike formatted ASCII and virtual array I/O, a CLOSE statement on a 
block I/O file does not write the contents of the I/O buffer to the file before 
closing it. Instead, you must perform all I/O operations with block I/O files 
explicitly, using GET and PUT statements. Be sure that your program 
writes the last record to the file before you close it. 

17.3 Reading and Writing Data - The GET and PUT Statements 

You perform input and output operations with block I/O files directly 
between the device and the I/O buffer that the OPEN statement creates. 
Specify all I/O in terms of single records, using the GET and PUT state¬ 
ments. The formats for GET and PUT are: 

GET#<e>tp>[,{®^^ .COUNT <«p> .USING <exp>] 

PUT #<«.p> [, {.COUNT <exp> .USING <exp>j 

If you do not use the RECORD or BLOCK option, the GET statement reads 
the next sequential block from the file open on the channel designated by 
the first expression. The system places the block in the I/O buffer that is 
associated with the channel. The size of the block depends on the character¬ 
istics of the device that the file is on (see Table 17-2). In block I/O, the 
RECORD or BLOCK option refers to a sector whose length is device¬ 
specific, not to a logical data record. 

When you use the RECORD or BLOCK options in a GET or PUT state¬ 
ment, the system accesses a specific block. For example: 

100 GET RECORD 8Z 


This statement reads the eighth block of the file opened on channel 4 into 
your I/O buffer. Note that the preceding seven records of the file need 
not be read. This feature, not available in formatted ASCII files, is called 
random access. 

Similarly, if you do not specify any of the options in the PUT statement, it 
writes the contents of the I/O buffer for the I/O channel onto the next 
sequential block of the file. The first expression specifies the channel num¬ 
ber on which you opened the file. 

The PUT statement writes a single block on the device. The exception to 
this is disk files. One PUT statement writes multiple disk blocks when you 
use the RECORDSIZE option in the OPEN statement to increase the I/O 
buffer size. 
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Table 17-2: 

Device Record Characteristics 

Device 

Record Characteristics 

Disk 

In file-structured processing, the default RECORDSIZE for disks is 612 
b)ftes, the length of a disk block. In non-file-structured processing, how¬ 
ever, the default RECORDSIZE depends on the device cluster size. 
(See the RSTS/E Programming Manual for information on non-file- 
structured processing.) 

You can specify a RECORDSIZE other than 512. When you do, though, 
keep this information in mind: 

1. The RECORDSIZE must be an even number. 

2. The GET and PUT statements transfer data in 512-byte units. 
Thus, you lose data when the RECORDSIZE is not a multiple of 612. 
In a GET, the system reads as many 512-b5rte units into the buffer 
as its size can accommodate and discards the portion of the last 
block that does not fit in the buffer. In a PUT, the system writes this 
last block as a partial block. The rest of this block has unpredictable 
contents. 

3. The RECORDSIZE value changes the buffer size, but it does not 
change the record number associated with each block of the disk 
file. For example, when you specify a RECORDSIZE of 1024, the 
system transfers two disk blocks in each GET and PUT. However, 
each record in the the file still has the same number as it does when 
you use a 512-byte buffer. Use the BLCKJK or RECORD option in 
GET and PUT statements to specify the correct record number for 
each read and write operation. (See Sections 17.3.1 and 17.3.2.) 

DECtape 

For file-structured DECtape, records are always 510 bytes long. For 
non-file-structured DECtape, records are always 512 characters. 

Magnetic tape 

When performing file-structured I/O, magnetic tape records are 
normally 512 characters. With non-file-structured I/O, magnetic tape 
records can be of any length. Only one record can be read per GET 
statement, and the record length cannot exceed the buffer size (as deter¬ 
mined by the RECORDSIZE option). The minimum record size is 14 
characters. 

Keyboard 

A keyboard record is a series of characters. The first delimiter marks 
the end of the record. The delimiter can be a RETURN, a LINE FEED, a 
FORM FEED, an ESCAPE, or a private delimiter (see the RSTS/E 
Programming Manual). 

Card reader 

A record consists of a single card. The RECORDSIZE option has no 
effect on card reader input. 

Paper tape 

RSTS/E reads a full buffer of input from the paper tape reader unless 
an end-of-tape is detected. 


17.3.1 BLOCK Option 

With disk files, you can perform random access I/O to any block of the file. 
Blocks in a disk file are always 512 bytes long and are logically numbered 
within the file from 1 to n, where n is the size of the file. 
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The BLOCK expression provides the logical block number of the file to the 
GET or PUT statement. The BLOCK option uses a real argument. This 
feature allows you to read and write specific blocks of files with more than 
65535 blocks. 

For example, assume that you open a disk file on channel 1. The following 
statement writes the contents of the I/O buffer associated with channel 1 
on blocks 10 through 99 of that disk file: 

200 PUT BLOCK I FOR 1 = 10. TO 89. 

You can read or write more than one physical block. Just assign a large I/O 
buffer to the file with the RECORDSIZE option in the OPEN statement. 
The size of the buffer does not affect the numbering of the blocks (512 bytes 
each) within the file. 

If you open a disk file on channel 1 with a RECORDSIZE of 1024 (which 
causes two 512-byte blocks to be written with each PUT), you can write a 
PUT statement as: 

200 PUT BLOCK I FDR 1=10. TO 98. STEP 2. 

When your program performs a random access GET or PUT on a disk file, 
the next GET or PUT statement on that channel accesses the next sequen¬ 
tial block if no BLOCK number is specified. For example: 

290 OPEN "DATA.DAT" AS FILE #1Z. RECORDSIZE 512Z 
300 GET »*1Z. BLOCK 99. 

310 PUT #1Z 

The PUT statement at line 310 writes block 100 of the disk file. 

NOTE 

Use of the BLOCK option in a GET statement is not compati¬ 
ble with other versions of BASIC. 

17.3.2 RECORD Option 

The RECORD option can also be used in GET and PUT statements to 
access a specific block. Unlike the BLOCK option, which uses a real argu¬ 
ment, the RECORD option accepts an integer argument that specifies the 
logical block number in the file. Thus, the RECORD option limits the direct 
specification of a block number to 32767 (the largest integer value). You 
cannot use the RECORD option to work with large files. Note that the 
BLC)CK and RECORD options are mutually exclusive. 

17.3.3 COUNT Option 

You can use the COUNT option in a PUT statement to specify the number 
of characters to write in the current record. The COUNT expression, how¬ 
ever, cannot be greater than the size of the I/O buffer. 


Block I/O 17-7 




The COUNT option is usually used in non-file-structured processing. For 
example, if magnetic tape unit 0 is open for non-file-structxired processing 
on channel 1, you can use the following statement to write an 80-character 
record: 

100 PUT #1Z. COUNT BOZ 

When you do not use COUNT, the PUT statement writes an entire buffer, 
regardless of whether the buffer contains data. 

The COUNT option used in a GET statement specifies the maximum num¬ 
ber of characters to be read in the current record regardless of the buffer 
size. For example, if magnetic tape unit 0 is open on channel 3, you can use 
the following statement to limit the GET operation to 50 characters: 

250 GET »3Z» COUNT 50Z 

When you do not use COUNT, the GET statement attempts to fill the 
entire buffer. 

Note that the RECOUNT variable (see Section 17.3.5) is set in all cases. If 
the amount of data read by the GET operation is less than the limiting 
value of COUNT, the RECOUNT variable contains the actual amount of 
data read. 

GET with the COUNT option works differently depending on the device 
type. For character-oriented devices (such as terminal, paper tape, or card 
reader), if the amoimt of data is greater than the limiting COUNT value, 
succeeding GET operations read the remaining data. For block-oriented 
devices (DECtape, magnetic tape, disk), the data beyond the limiting 
COUNT value in the last block is lost. Succeeding GET operations read 
from the next block. 


NOTE 

Use of the COUNT option in a GET statement is not compati¬ 
ble with other versions of BASIC. 

17.3.4 USING Option 

The RECORDSIZE option in the OPEN statement defines the size of an I / O 
buffer. The USING option can be used in a GET or PUT statement to 
specify eui offset into that I/O buffer. That is, the USING option can cause a 
(JET or PUT to begin a read or write operation at a specified byte in the 
buffer. For example: 

200 GET «1Z. COUNT 10Z» USING 20Z 

Line 200 reads up to 10 characters into the I/O buffer associated with 
channel 1, beginning at a position 20 bytes into the buffer. 
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NOTE 


Use of the USING option in a GET statement is not compati¬ 
ble with other versions of BASIC. 

17.3.5 RECOUNT Variable 

Non-file-structured devices can read less than a full buffer of data. To 
determine how much data was actually read, RECOUNT, a BASIC-PLUS 
variable, contains the number of characters read following every input 
operation. RECOUNT is used primarily for non-file-structured input; how¬ 
ever, you can also use it with file-structured devices. 

RECOUNT is set by every input operation on any channel {including chan¬ 
nel 0). It is essential that you test or copy the RECOUNT value immedi¬ 
ately after an INPUT or GET statement. The value of RECOUNT is not 
defined if an error occurs in the I/O operation. In addition, RECOUNT does 
not return useful information in immediate mode. 

17.3.6 Extending Disk Fiies 

When you create a disk file with an OPEN FOR OUTPUT (or OPEN) 
statement, the file has a length of 0. As blocks are written, the file grows in 
length. This growth is called extending the file. 

A more exact description of the disk file extension process follows: 

1. The system checks to see if there is room in the last cluster of a file for a 
new block. (The cluster size defines the minimum increment by which 
you can extend a file on the disk. A file need not occupy all blocks 
within the cluster.) 

2. K so, then the file length is increased and previously unused space in 
that cluster is used. 

3. If not, then a new cluster is appended to the file. Go back to Step 1. 

The amount of space that the system allocates to a disk file may be greater 
than the file length. For example, if the file cluster size is four and you 
have written the first six blocks of that file, the file is six blocks long but 
has eight blocks (two clusters) of space. 

You can extend a disk file by writing beyond the current end-of-file. How¬ 
ever, a program must have write access to a file in order to extend it. 

You can extend a file that is open in update mode, but only if you first lock 
block 1 of the file. You must make a contiguous file non-contiguous before 
you can extend it. (See the RSTS IE Programming Manual for more infor¬ 
mation about update mode and contiguous files.) 

You can extend a file by a number of blocks at one time. For example: 

100 OPEN "DATA.DAT" FOR OUTPUT AS FILE «1X 
110 PUT iHZ. BLOCK 100. 
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These statements create a file DATA.DAT and extend it immediately to 
100 blocks. The system overhead for extending a file by a single block and 
by many blocks is nearly the same. Therefore, it is much more efficient to 
immediately extend a newly created file to its final length than to extend it 
many times in increments of a single block. Whenever you know the final 
size of a file, you should extend it to its full size in a single operation. 

17.3.7 Alternate Buffer I/O 

With normal I/O, moving data from one device to another requires two 
buffers, one for the input device and one for the output device. Your pro¬ 
gram also has to move data from the input buffer to the output buffer. But a 
special technique in BASIC-PLUS allows you to bypass one buffer. This 
technique is c^led "alternate buffer I /O.” 

With alternate buffer I/O, you can: 

• Move data from an input buffer directly to an output device, without 
using an output buffer. 

• Move data from an input device directly to an output buffer, without 
using an input buffer. 

• Move data between input or output devices and a temporary buffer set up 
as a work area. 

These techniques are useful for copying one file to another and for record 
blocking and deblocking. (You block and deblock records with the FIELD 
statement, which is described in Section 17.4.1. For an example of record 
blocking and deblocking, see Section 17.6.) 

To perform alternate buffer I/O, you replace the channel number in a GET 
or PUT statement with an expression of the form: 

SWAPZ<BZ) + IZ 

B% is the channel number of the buffer to be used, and 1% is the channel 
number on which I/O occurs. 


The following example shows a fast copy, using alternate buffer I/O: 


05 ON ERROR GO TO 9000 

10 OPEN "RANDOM" FOR INPUT AS FILE »1Z 

20 OPEN "COPY" FOR OUTPUT AS FILE «2Z» RECORDSIZE 327G7Z+1Z+2Z 

30 GET »1Z 

40 PUT *SWAPZ(1Z) + 2Z 

50 GO TO 30 

60 PRINT "FILE COPIED" 

70 CLOSE »1Z. #2Z 

80 STOP 

9000 IF ERR=11Z AND ERL=30Z THEN & 

RESUME 60 & 

ELSE ON ERROR GO TO 0 
32767 END 
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In this example, the input device is open on channel 1 and the output device 
is open on channel 2. The GET statement in line 30 moves data from the 
input device into the input buffer. The PUT statement in line 40 moves the 
contents of the input buffer directly to the output device open on channel 2. 
With normal I/O, you have to write two FIELD statements, one for each 
buffer, and use an LSET statement to move the data from one buffer to 
another (see Section 17.4). 

You can also use alternate buffer I/O as a spacesaving technique in pro¬ 
grams that transfer data among several different files. Open each file with 
a small bviffer size (for example, 2 b 3 d;es) because you will not be using 
these I/O buffers for data transfers. Open the null device (NL;) to create a 
"scratch buffer” at the size you need for data transfers. (You have to use the 
RECORDSIZE option when you open the null device because its default 
buffer size is 2 bytes.) You can then use alternate buffer I/O to transfer 
data from an input file to the scratch buffer and from the scratch buffer to 
an output file. 

You use the expression SWAP%(B%) + 1% to specify alternate buffer I/O 
because BASI()-PLUS stores information about an I/O channel in one 
word of memory. The low byte of the word contains the channel number; 
the high bjd* of the word contains the channel number of the buffer to use 
for I/O on that channel. When you specify only a channel number, the high 
byte of this word is 0. BASIC-PLUS uses the value in the low byte as both 
the buffer number and the channel number. 

The expression SWAP%(B%) + 1% creates a one-word value that contains a 
nonzero buffer number in the high byte and a channel number in the low 
byte. For example: 

SI*IAPZ( 12> + 2Z 

This expression combines the integers 1% and 2% into a value with the 
internal format: 


1 2 


High LOW 
Byte Byte 


When you use this expression in a GET or PUT statement, BASIC—PLUS 
tells the system to transfer data to or from the buffer specified in the high 
byte instead of the I/O channel’s default buffer. (See Section 17.5.2 for 
more information about SWAP%.) 

17.4 Accessing the I/O Buffer 

So far this chapter has described how to read and write data between a 
device and an I/O buffer with GET and PUT statements. This section 
describes the statements you use to make data in an I / O buffer available to 
your program. 
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BASIC—PLUS has three statements that operate on data in an I/O buffer: 
FIELD, LSET, and RSET. FIELD lets you access the buffer as string data, 
and LSET and RSET move string values from your program into the buffer. 
With these statements, you can access and modify each byte of an I/O 
buffer. 

17.4.1 FIELD Statement 

The FIELD statement dynamically associates string variables with parts of 
an I/O buffer. The FIELD statement has the form: 

FIELD #<exp>,<expl> AS <string varl>[,<exp2> AS <8tring var2>,...] 

The <exp> is a channel number associated with some file by an OPEN 
statement, <expl> is the length in characters of the associated string vari¬ 
able, and <string varl> is a string variable name. The names are associ¬ 
ated from left to right with successive characters in the I/O buffer assigned 
to the designated channel number. For example: 

75 FIELD «27. > lOZ AS A$ > ZOX AS B$ j 3Z AS F$ 


A$ 

B$ 

F$ 



--20-► 

3 








As shown in the previous diagram, statement 75 associates three strings, 
A$, B$, and F$ in the I/O buffer, with lengths of 10, 20, and 3 characters, 
respectively. This statement represents a total number of 33 characters. 
The total number of characters must be less than or equal to the actual I/O 
buffer size (this depends on the device and the RECORDSIZE option; see 
Section 14.3.1). 

FIELD statements do not move data. Instead, they permit direct access to 
sections of the I/O buffer through string variables. The effect on a string 
variable is temporary and is nullified by any attempt to assign a value to 
the variable (other than with the LSET and RSET statements; see Section 
17.4.3). For example: 

100 OPEN 'FILE' AS FILE *2X 
110 FIELD »2X, 5Z AS A$ 

120 LET A* = 'ABODE' 


The LET statement at line 120 removes the string variable A$ from the 
I/O buffer. 

A FIELD statement is an executable statement. You can change a buffer 
description at any time by executing another FIELD statement. For exam¬ 
ple, suppose that each block of a disk file contains sixteen 32-character 
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subrecords. Each subrecord consists of one 5-character field and one 
27-character field. To extract the eighth subrecord from the I/O buffer, you 
can execute the following statement: 

200 FIELD ZZaX AS D$» 5Z AS B$> 27Z AS A$ 


t 

i 1 

1 1 

t I. 


ii i 


r-r -n- 


A$ 






1 

J _ Li_ 


^ k' L 

bytes 


Line 200 causes the string variables B$ and A$ to point to the desired 
subrecord. The string D$ is created to permit the first seven subrecords 
(7*32 = 224) to be skipped. You can use an even more general statement to 
obtain any of the subrecords in the I/O buffer: 

190 FOR IX = OX TO 15X 

200 FIELD «1X» IX*32X AS D*» 5X AS . 27X AS A$ 

210 NEXT IX 



This FOR loop shows how you can repetitively execute a FIELD statement. 
Each time the FIELD statement is executed, 1% contains the number of the 
subrecord that B$ and A$ are to contain, as an integer from 0 to 15. When 
1% = 0, for example, the expression I%*32% equals 0. B$ points to the first 
subrecord in the buffer. When I% = 1, however, the expression I%*32% 
equals 32, so B$ now points to the first subrecord beyond the 32nd charac¬ 
ter of the buffer. Each single increment of 1% moves B$ 32 characters 
further into the buffer. 

You can also use subscripted string variables in FIELD statements. For 
example, the following statements allocate the subrecords described in the 
previous example to two string arrays: 

300 DIM A$(15X)f B$(15Z) 

310 FOR IX = OX TO 15X 

320 FIELD »1X. IX»32X AS D*» 5X AS B$(IX)» 27X AS A*(IX) 

330 NEXT IX 


B$(0) B$(1) B$(2) B$(3) B$(4) B$(5) B$(6) B$|7) 

-A--A--A--A— 


A$(0) 

A$(1) 


A$(2) 

A$(3> 

A$(4) 

A$(5) 

AS(6) 

A$(7) 







1 

1 

1 





I *1 *1 1 
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With each iteration of the FIELD statement at line 320, the dummy string 
D$ increases by 32 characters. This makes the displacement from the start 
of I/O buffer to the string B$(I%) equal to 32 times 1% characters. Once the 
system executes this loop, it fixes the position of each string in the arrays 
A$ and B$. A$(0) and B$(0) point to the first subrecord, and A$(15) and 
B$(15) point to the last. 

You can also use more than one FIELD statement in a program to define 
the same buffer in different ways. For example: 

20 FIELD flOI AS WHOLE.FIELD* i 

\ FIELD #1%. lOZ AS A*. lOZ AS 6*. lOZ AS C* 

The first FIELD statement associates the first 40 characters of a buffer 
with the variable WHOLE.FIELD$. The second FIELD statement associ¬ 
ates the first 30 characters of the same buffer with the variables A$, B$, 
and C$. Later program statements can refer to any of these variables. 
(The first example in Section 17.6 illustrates this use of multiple FIELD 
statements.) 

You must not define virtual array strings as string variables in a FIELD 
statement. When you define strings as virtual arrays, they must be in a 
fixed place, in both a disk file and the I/O buffer, for that file. Attempting 
to specify a virtual array string variable in a FIELD statement has no 
effect on the virtual array string. 

17.4.2 The LSET and RSET Statements 

After you define string variables as part of the I/O buffer with a FIELD 
statement, you can store values in these variables without moving them 
from the I/O buffer. The LSET and RSET statements store values in a 
string variable without redefining the string position. These statements 
have the form: 

LSET <string var> [,<string var>,...] = <8triiig> 

RSET <8tring var> [,<8tring var>,...] = <8tring> 

Here <string var> is any legal existing string variable name. You can 
separate multiple string variable names by commas. The <string> is any 
legal string expression. 

The LSET and RSET statements store the value of the string expression 
into the designated string or strings. The string previously stored in the 
variable is overwritten, although the length of the string is not changed. 

If a new string is longer than an existing string, the system truncates the 
new string. If a new string is shorter than an existing string, it is either 
padded with spaces on the right by LSET or padded with spaces on the left 
with RSET. LSET causes the string to be left-justified in the field, and 
RSET causes the string to be right-justified. 
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LSET and RSET normally move data to an I/O buffer, as this section 
describes. They can also move a value into any string variable in your 
program. 

17.4.3 Differences between the LET Statement and the LSET/RSET 
Statements 

The LET statement cannot place string values into an I / O buffer because it 
redefines the string variable. Another restriction on LET occurs when a 
statement equates two strings: 

100 LET A$ = B* 

To avoid unnecessary character manipulation, BASIC—PLUS makes A$ 
and B$ to point to the same string in memory. Normally, any operation 
that alters B$ causes that string to be moved, so that no conflict arises. 
However, LSET and RSET do not move strings; they change existing 
strings in a fixed position. 

If you change the value of B$ in line 100 with an LSET or RSET statement, 
then you also change the value of A$. For example: 

LISTNH 

400 B$ = “ABC" 

410 A« - 6$ 

420 LSET B$ = "XYZ" 

430 PRINT A* 

3Z7B7 END 

Ready 

RUNNH 

XYZ 

Ready 


Both A$ and B$ contain "XYZ” after the execution of line 420. 

Note that if you define the string B$ in this example with a FIELD state¬ 
ment as pointing to a subrecord in some I/O buffer, the string A$ also 
points to the same I/O buffer (being identical to B$). Executing a GET 
statement to read another record into the I/O buffer then changes the 
value of A$ as well as B$. For this reason, you should use LSET and RSET 
only for block I/O operations; using these statements for other purposes 
may cause unexpected results. 

When the strings A$ and B$ should not be physically identical, use the 
following method to move the string B$ into the string A$: 

300 LET A* = B* + “" 

This statement causes BASIC—PLUS to create a new string for A$, rather 
than pointing A$ and B$ to the same string. 
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17.5 Converting Numeric Data - CVT Functions and SWAP% 

This section describes functions that: 

• Convert data between numeric and string formats 

• Swap the high and low order bytes of an integer 

Both t3T)es of functions are useful in block I/O. 

17.5.1 CVT Conversion Functions 

The BASIC—PLUS FIELD, LSET, and RSET statements let you access data 
in the I/O buffer as string data only. To process numeric data in your 
program, you must convert it from string to numeric format after you move 
it fmm the I/O buffer. After processing, you must convert the numeric data 
back to string data before you transfer it to the I/O buffer for output. 

BASIC-PLUS provides four CVT conversion functions to convert data 
between string format and integer or floating-point formats. Table 17—3 
lists these four conversion functions. (A fifth CW function, CVT$$, helps 
you process string data. See Chapter 10.) 

NOTE 

Do not confuse the CVT conversion functions with the 
CHANGE statement or the NUM$ and VAL functions. 


Table 17-3: CVT Conversion Functions 


Function Form 

Operation 

A$ = CVT%$(I%) 

Maps an integer into a two-character string. 

1 % = CVT$%(A$) 

Maps the first two characters of a string into an integer. If the 
string has fewer than two characters, BASIC-PLUS appends null 
characters as required. 

A$ = CVTF$ (X) 

Maps a floating-point number into a four- or eight-character string 
(depending upon whether you are using the two-word or four-word 
math package on the system). You can determine the current math 
package by examining LEN(CVTF$(0)). 

X = CVT$F (A$) 

Maps the first four or eight characters (depending upon whether 
you are using the two-word or four-word math package on the sys¬ 
tem) of a string into a floating-point number. If the string has fewer 
than the required number of characters, BASIO-PLUS appends 
null characters. 


These CVT functions affect the value’s storage format, but not its value. 
Each character in a string requires one byte of storage (8 bits). Hence 
characters can assume (decimal) values from 0 through 255 only. A 16-bit 
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quantity can be defined as either an integer or a two-character string. You 
can similarly define two-word fioating-point numbers eis four-character 
strings and four-word floating-point numbers as eight-character strings. 

The CVT functions that change storage format perform two important 
functions: 


• They permit dense packing of data in records. For example, you can pack 
any integer value between -32768 and 32767 in a record in two charac¬ 
ters using CVT%$. This is true only for integers between -9 and 99 when 
data is stored as ASCII characters. 

• Converting the internal numeric representation to an ASCII string (as 
with the NUM$ function) is a more time-consuming process than that 
performed by the CVT functions. Thus, the CVT fimctions speed the proc¬ 
essing of a large amount of data in a file. 

Use the CVT functions in LSET, RSET, and LET statements to transfer 
numeric data between an I/O buffer and your program. For exsimple, the 
following statements store two integers, U% and CL%, and two single¬ 
precision floating-point numbers, X and Y, in the I/O buffer for channel 8: 

200 FIELD 2Z AS U$ > 2X AS CL« > OX AS X* t 4X AS Y$ 

210 LSET U$ = CVTX*<UX) 8. 

\ LSET CL* * COTX^ICLX) t, 

\ LSET X* = CVTF*<X) 8. 

\ LSET Y* = CVTF*(Y) 


You can retrieve this data from the buffer by converting it from string to 
numeric form: 


220 LET UX = C<.»T*X(U*) 8< 

\ LET CLX = CyT*X(CL*) 8: 
\ LET X = CVT*F(X*) 8 
\ LET Y = C0T*F(Y*) 


Use LSET or RSET statements to move data from your program into the 
I/O buffer; use LET statements (or other statements that assign values to 
variables) to move data from the I/O buffer to your program’s data area. 


17.5.2 SWAP% Function 

The SWAP% function swaps the low order byte of an integer with its high 
order byte. SWAP% returns an integer value with the bytes reversed. For 
example: 

PRINT SWAPX(IX) 

256 

PRINT SWAPX(2BB32X) 

2152 
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The following diagrams show the internal formats of the integers 1% and 
26632% before and after using SWAP%: 


1 % = 
SWAP%(1%) = 


26632% = 

SWAP%(26632%) = 

High Byte Low Byte 



SWAP% has several different uses in BASIC-PLUS programming. For 
example, Section 17.3.7 shows the use of SWAP% in alternate buffer I/O to 
create a one-word value that contains a channel number in the low byte 
and a nonzero buffer number in the high byte. SWAP% is useful for reading 
data returned by system function calls. See Section 11.7.4.3 for an example 
and the RSTS/E Programming Manual for details. You also need to use 
SWAP% with the CVT functions when you read nvuneric data using block 
I/O that was written using a different I/O method. See Section F.4 for 
more information. 


17.6 Block I/O Examples 

The examples in this section show various ways to use block I/O. Some 
examples are complete programs, while others are program fragments. 
These examples are intended as an introduction — block I/O has many 
more possible uses. 

The following example prints a line on the terminal: 


5 EXTEND 

10 OPEN 'KB;' FOR OUTPUT AS FILE »1Z ICreate 12B-byte buffer 
20 FIELD •IX. 40X AS WHOLE.FIEL0$ IDefine entire buffer S. 

& 

S FIELD «1X. lOZ AS A$. lOZ AS B$ . lOZ AS C* 8, 

IThen define three subfields in same buffer & 


30 LSET WHOLEtFIELD$ = SPACE$(40Z) 
aO LSET A$ = ‘'12345" 

\ RSET B$ = "67890" 

\ RSET C$ = "OWXYZ" 

50 PUT COUNT 40Z 

60 PRINT nl %, 

32767 END 


•Preload buffer with blanks 
•Load first 10 characters & 

ILoad next 10 characters & 

ILoad last 10 characters 

•Write this buffer 

IShow that PUT ^iues no <CR><LF> 


When you run this program, it prints: 
12345 67890 UWXY2 


Ready 
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In this example, the OPEN statement at line 10 opens KB: with the default 
buffer size (128 b 5 des). The FIELD statements at line 20 define the buf¬ 
fer, once as a 40-character string WHOLE.FIELD$ and once as three 
10-character strings A$, B$, and C$. 

The LSET statement at line 30 preloads WHOLE.FIELD$ (the first 40 
characters of the buffer) with blanks to delete whatever data is in that part 
of the buffer. (In this case, the blanks delete the program header line that 
BASIC-PLUS prints when you run the program. RUNNH stops the header 
from being printed, but it is still in the buffer.) 

The LSET and RSET statements at line 40 use the variables A$, B$, and 
C$ to load the first 30 characters of the buffer with the line to be printed. 
(Note that both LSET and RSET write blanks into unused portions of the 
10-character fields.) The PUT statement prints the line, and the PRINT 
statement shows that the PUT statement does not output a carriage 
return/line feed. 

The next example is a program to move data in a file named REPORT.FIL 
from a disk to the line printer: 


50 EXTEND 

110 OPEN 'REPORT.FIL' AS FILE -IX 
120 ON ERROR GOTO 200 

130 OPEN 'LP:' FOR OUTPUT AS FILE *2%, RECORDSIZE 512X 
IflO FIELD wlX* 512X AS A* 

150 FIELD «2X. 512X AS B» 

160 GET «1X 
170 LSET B» = A$ 

ISO PUT #2X 
190 GOTO 160 
200 CLOSE «1X. «2X 
327E7 END 


In this example, the buffers for the line printer and the disk file are both 
initialized to 512 characters. The FIELD statements at lines 140 and 150 
define A$ and B$ to refer to these buffers. 

The LSET statement transfers data read at line 160 to the line printer 
buffer. (RSET can also be used here because A$ and B$ are the same 
length.) The PUT statement at line 180 outputs the data to the line printer. 
The loop terminates when the ”?End of file on device” error occurs. The 
ON ERROR GOTO statement transfers control to line 200, which closes both 
I/O channels. 

Note that you can write a more efficient version of this program using 
alternate buffer I/O, which is described in Section 17.3.7. 

The next two examples show how you can use CVT functions to store 
numeric data in compact internal form. The first program creates a mag¬ 
netic tape file that has 26 records in each block. Each record consists of an 
integer in two-bjrte internal format and a one-byte string. The second pro¬ 
gram reads the file and prints the data on the terminal. 
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50 EXTEND 

100 DIM INTEGER$(25X) f LETTER$(25X) ‘Define arrays of string & 

luariable names 

200 OPEN 'MMO;CVT.BLK ' FOR OUTPUT AS FILE nlX , REC0RDSI2E 79X & 


300 FIELD ullf AS D%* 

2X AS INTEGER$(IX)t 
IX AS LETTER$(IX> 

FOR IX = OX TO 25X 

aOO FOR IX =0X TO 25X 

410 LET JX = IX + 65X 

500 LSET INTEGER$(IX) = CUTX$(JX) 

600 LSET LETTER$(IX) = CHR$(JX) 

700 NEXT IX 

800 PUT #1X 

32767 END 


•Offset over previous records & 

•Storase for converted integer & 
•Storage for l-character string & 

•FOR modifier defines record 26 times & 


!Now build one physical block 

IStore “internal” integer 
•Store corresponding letter 

•Mrite the record onto tape 


50 

100 

200 

210 

300 


EXTEND 

DIM INTEGER$(25X) > LETTER$(25X) 
OPEN 'MM0:CUT4BLK ' FOR INPUT AS 
GET #2X 

FIELD «2X t IX*3X AS D$ » 

2X AS INTEGER$(IX)# 
IX AS LETTER$(IX) 

FOR IX = OX TO 25X 


INTEGERX(25X) 

FILE «2X» RECORDSIZE 78X 

•Offset over previous records t 
{Converted intei^er & 
!l-character string &c 
•FOR modifier defines record 26 


times & 


400 FOR IX =0X TO 25X 

500 LET INTEGERX(IX) = COT$X (I NTEGER$ (IX) ) {Convert stored integer back &= 

{to internal fo rmat 

600 PRINT INTEGERX< IX) f LETTER$(IX) {Print each inte^fer and letter 

700 NEXT IX 
32767 END 


The next example shows how you can use FIELD statements to block and 
deblock records, ''Deblocking” a record refers to the process of breaking a 
physical record from an input device into the logical components that you 
process in your program. "Blocking” refers to the process of converting 
these logical components back to their physical form for output. In format¬ 
ted ASCII and virtual array I/O, BASIC-PLUS handles blocking and 
deblocking for you. In block I/O, you block and deblock records by manipu¬ 
lating data in a buffer with FIELD, LSET, and RSET statements. 


100 GET #2X 

200 FOR IX = OX TO 420X STEP SOX 
300 FIELD n2Xf IX AS D$» 

BOX AS R$ 


! 4 

400 NEXT IX 
500 PUT «2X 


{Read a block 

{Process each record in block 

{D$ is not used# it's Just an offset & 

{This is the current record & 

{Process the current record & 

& 

{Field next record in block 
{Rewrite modified block 
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The following program fragment shows how to use the null device and 
FIELD to set up a buffer to use for breaking down an arbitrary string: 


50 EXTEND 

300 OPEN 'NL:' AS FILE #121> REC0R0SI2E 1321 

400 FIELD #121f 1321 AS WHOLE*LINE$# 

\ FIELD #121» 101 AS ITEM$f 
41 AS D$ « 

501 AS DESCRIPTION$f 
61 AS D%f 
161 AS 0UANTITY$» 

51 AS D%f 

181 AS UNIT*PRICE$ » 

51 AS D%f 

181 AS TTL*PRICE$# 

21 AS D$ 


'Create a dummy buffer & 
!(Won't be read or written) 
IGiue a name to whole buffer & 
!Create subfields in buffer & 
IWon't reference D$ fields 8e 

& 

& 

& 

& 

& 

& 

& 

& 

& 

& 


500 INPUT LINE #L1# D$ 

\ LSET WHOLE«LINE$ = L$ 

\ QUANTITY = UAL(QUANTITY«) 

\ UNIT.PRICE = UAL(UNIT.PRICE$) 
\ EXTENDED.PRICE = OAL(EXTENDED 


!Read a record from input file & 

IMoue it into this buffer & 

iChanse strings into numbers & 

Iwhere appropriate & 

PRICE$) 


17.7 UNLOCK Statement 

Block I/O gives you access to a RSTS/E feature called file sharing. To use 
this feature, you open a file in update mode (MODE 1%). Update mode 
gives multiple users write access to a file. At the same time, it prevents 
simultaneous writing of the same data. When a program performs a read 
operation on a file open in update mode, the system "locks” the blocks that 
are accessed. This "lock,” called an implicit lock because the system does it 
automatically, ensures that no other user can modify the blocks. 

You can release an implicit lock with the UNLOCK statement. It has the 
form: 

UNLOCK #<expression> 

The <expression> is the channel number of the file that is open for update. 

You can explicitly lock and unlock blocks in a file with the SPEC% func¬ 
tion. See the RSTS/E Programming Manual for more information about 
update mode and the SPEC% function. 
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Appendix A 
Language Summary 


A.1 Summary of Variable Types 

In EXTEND mode, a variable name can consist of a letter, followed by 0 to 
29 additional characters, each a letter, digit or a period. 


Examples 

PER.DIEM.FACTOR 
ZX 

BRANCH.CONTROLZ 
HEADING.A3l.FORMS 


(floating-point variable) 

(integer valid also in NOEXTEND) 
(integer variable) 

(string variable) 


DECK.OF.CARDSSO .12) (string array) 

In NOEXTEND mode a variable name consists of a letter optionally fol¬ 
lowed by a digit. The rules for specifying integers, strings, and dimension 
elements are the same in EXTEND and NOEXTEND modes. 


Type 


Variable Name 


Examples 


Floating-Point 

A variable name with no suffix 

A 

I 

X3 


Integer 

Any variable name followed by a % 
character 

D7I 


Character String 

Any variable name followed by a $ 
character 

M* 

Rl$ 


Floating-Point Array 

Any floating-point variable name 
followed by one or two dimension 
elements in parentheses 

S(4) 

N2(B) 

E(5tl) 

V8(3#3) 

Integer Array 

Any integer variable name followed 
by one or two dimension elements 
in parentheses 

AX(2) 

E3X(a) 

11(3*5) 
R2X(2 *1) 

Character String Array 

Any string variable name followed 
by one or two dimension elements 
in parentheses 

C$( 1 ) 
A2$(8) 

S$(8*5) 
Ml$(a *2) 
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A.2 Summary of Operators 

Type Operator Operates On 


Arithmetic 

— 

Unary minus 

Numeric variables and constants. 


"or 

Exponentiation 



♦,/ 

Multiplication, division 




Addition, subtraction 


Relational 

= 

Equals 

String or numeric variables and 


< 

Less than 

constants. 


< = 

Less than or equal to 



> 

Greater than 



> = 

Greater than or equal to 



<> 

Not equal to 




Approximately equal to (num¬ 
bers); Identically equal to 
(strings) 


Logical 

NOT 

Logical negation 

Relational expressions composed 

AND 

Logical product 

of string or numeric elements, 


OR 

Logical sum 

integer variables, or integer 


XOR 

Logical exclusive or 

expressions. 


IMP 

Logical implication 



EQV 

Logical equivalence 


String 

+ 

O>ncatenation 

String constants and variables. 

Matrix 


Addition and subtraction of 
matrices of equal dimensions, 
one operator per statement 

Subscripted variables. 



Multiplication of conformable 
matrices 




Scalar multiplication of a 
matrix 



A.3 Summary of Functions and Variables 

This summary includes BASIC—PLUS standard functions, optional func¬ 
tions, and built-in variables (such as ERL). 

Each function or variable has the format: 

Y=function 


or 

Y=variable 

Y is the value returned. Y with no suffix means that the function or varia¬ 
ble returns a floating-point value. A % suffix means that the function or 
variable returns an integer value; a $ suffix means that the function or 
variable returns a string value. 

Function arguments can be floating-point, integer, or string. A function 
argument without a suffix is a floating-point argument; a % or $ suffix 
in^cates an integer or string argument. 
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You can always replace a floating-point argument with an integer 
argument. You can also replace an integer argument with a floating-point 
argument (an implied FIX is done) except in the CVT%$ and MAGTAPE 
functions. (The 1% argument in these fimctions means you must supply an 
integer.) However, for the greatest efficiency, use an argument of the t}^ 
shown. 

Type Function Description 


Mathematical 

Functions 

(Optional) 


Y=ABS(X) 

Y=ATN(X) 

Y = COS(X) 
Y=EXP(X) 

Y = FIX(X) 

Y = INT(X) 


Y=LOG(X) 

Y=LOG10(X) 

Y = PI 

Y = RND 

Y=RND(X) 

Y=SGN(X) 

Y-SIN(X) 

Y = SQR(X) 
Y=TAN(X) 

Print Functions Y% = CCPOS(X%) 

or 

Y%*POS(X%) 

Y$=TAB(X%) 


String Functions Y%=ASCn(A$) 

Y$ = CHR$(X%) 


Returns the absolute value of X. 

Returns the arc tangent (in radians) 
ofX. 

Returns the cosine of X, where X is in 
radians. 

Returns the value of e^X, where 
e = 2.71828... 

Returns the truncated value of X, 
SGN(X)*INT(ABS(X)). 

Returns the greatest integer in X that 
is less than or equal to X. 

Returns the natural logarithm of X, 
log(e)X. 

Returns the common logarithm of X, 
log(10)X. 

Returns the constant 3.14159.... 

Returns a random number between 0 
and 1. 

Returns a random number between 0 
and 1. 

Returns the sign function of X; +1 if 
positive, 0 if zero, -1 if negative. 

Returns the sine of X, where X is in 
radians. 

Returns the square root of X. 

Returns the tangent of X, where X is 
in radians. 

Returns the current position of the 
print head for I/O channel X%; chan¬ 
nel 0% is your terminal. 

Moves print head to position X% in the 
current print record, or is disregarded 
if the current position is beyond X%. 
(The first position is counted as 0.) 

Returns the ASCII value of the first 
character in the string A$. 

.Returns the character that has the 
ASCII value of X. Only one character 
is generated. 

(continued on next page) 
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Type Function Description 


String Functions Y$ = CVT%$(I%) 

Maps an integer into a two-character 
string. 

Y$ = CVTF$(X) 

Maps a floating-point number into a 
four- or eight-character string. 

Y% = CVT$%(A$) 

Maps the first two characters of string 
A$ into an integer. 

Y=CVT$F(A$) 

Maps the first fotir or eight characters 
of string A$ into a floating-point 
number. 

Y$=CVT$$(A$,I%) 

Converts string A$ to string Y$ 
according to the value of 1%. 

Y$ = RAD$(N%) 

Converts an integer value to a three- 
character string; is used to convert 
firom Radix--50 format to ASCII (see 
the RSTS/E Programming Manual). 

Y% = SWAP%(N%) 

Causes a byte swap operation on the 
two bytes in the integer variable N%. 

Y$=STRING$(N1%,N2%) 

Returns string Y$ of length Nl%, 
composed of characters whose ASCII 
decimal value is N2%. 

Y$ = LEFT(A$,N%) 

Returns a substring of the string A$ 
firom the first character to the N%th 
character (the leftmost N% charac¬ 
ters). 

Y$ = RIGHT(A$^%) 

Returns a substring of the string A$ 
from the N%th to the last character 
(the rightmost characters of the string 
starting with the N%th character). 

Y$ = MID(A$,N1%,N2%) 

Returns a substring of the string A$ 
that is N2% characters long and starts 
with character Nl% (the characters 
between and including the Nl% to 
Nl% + N2%-1% characters). 

Y% = LEN(A$) 

Returns the number of characters in 
the string A$, including trailing 
blanks. 

Y%=INSTR(N1%,A$,B$) 

Indicates a search for the substring B$ 
within the string A$ beginning at 
character position Nl%. Returns a 
value 0 if B$ is not in A$. Returns the 
character position of B$ if B$ is in A$ 
(character position is measured from 
the start of the string). 

Y$ = SPACE$(N%) 

Returns a string of N% spaces; is used 
to insert spaces within a character 
string, 

(continued on next page) 
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Type 


Function 


String Functions 


String Arithmetic 

Functions 

(Optional) 


System Functions 
and Variables 


Description 


Y$ = NUM$(N%) 


Y$ = NUM1$(N) 


Y = VAL(A$) 


Y$ = XLATE(A8,B$) 


Returns a string of numeric characters 
representing the value of N% as it is 
output by a PRINT statement. 

For example: 

NUM$(1.0000) = (space)l(space) 
NUM$(—1.0000)= —l(space). 

Returns a string of characters repre¬ 
senting the value of N%. NUM1$ is 
similar to the function NUM$, except 
that it does not return spaces or 
E-format results. 

Computes the numeric value of the 
string of numeric characters A$. For 
example: 

VAL(M5") = 15 

If A$ contains any character not 
acceptable as numeric input with the 
INPUT statement, an error results. 

Translates A$ to the new string Y$ 
using the table string B$. 


Y$ = SUM$(A$3$) 

Y$ = DIF$(A$,B$) 

Y$ = PROD$(A$,B$,P%) 

Y$ = QUO$(A$,B$,P%) 

Y$ = PLACE$(A$,P%) 

T% = COMP%(A$,B$) 

Y$ = DATE$(0%) 


Returns a numeric string equal to the 
arithmetic sum of numeric strings A$ 
and B$. 

Returns a numeric string equal to 
the arithmetic difference A$-B$ of 
numeric strings A$ and B$. 

Returns a numeric string equal to the 
product of numeric strings A$ and B$, 
rounded or truncated to P% places. 

Returns a numeric string equal to the 
arithmetic quotient A$/B$ of numeric 
strings A$ and B$, roimded or trun¬ 
cated to P% places. 

Returns a numeric string equal to the 
numeric string A$, rounded or trun¬ 
cated to P% places. 

Returns a value reflecting the result of 
an arithmetic comparison between nu¬ 
meric strings A$ and B$. T%=-1 for 
A$<B$, 0 for A$ = B$, and 1 for 
A$>B$. 

Returns the current date in the 
format: 

02~riar-71 

or 

71.03.02 

(continued on next page) 
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Type 


Function 


System Functions 
and Variables 


Y$ = DATE$(N%) 


Y$=TIME$(0%) 

Y$=TIME$(N%) 


Y = TIME(0%) 
Y=TIME(1%) 

Y = TIME(2%) 

Y=TIME(3%) 

Y = TIME(4%) 
Y% = STATUS 
Y% = BUFSIZ(N) 
Y% = LINE 

Y% = ERR 


Y% = ERL 


Description 

Returns a character string correspond¬ 
ing to a calendar date: 

N% = (day of year) + [{number of years 
since 1970)*1000] 

DATE$(1%) = 01-Jan-70or 

70*01*01 

Returns the current time of day as a 
character string: 

TIME$(0%) == 05:30 PM or 17:30 

Returns a string corresponding to the 
time at N% minutes before midnight. 

For example: 

TIME$(1%) = lls59PMor 

23:50 

TIME$(1440%) = 12:00 AM or 
00:00 

TIME$(721%) = 11:59 AM or 

11:59 

Returns the clock time in seconds since 
midnight as a floating-point number. 

Returns the central processor time 
used by the current job in tenths of 
seconds. 

Returns the connect time (during 
which you are logged into the system) 
for the current job in minutes. 

Returns the decimal number of kilo- 
core ticks (KCTs) that this job uses. 

Returns the decimal number of min¬ 
utes of device time that this job uses. 

Returns the status of the I/O channel 
most recently opened. 

Returns the buffer size of the device or 
file open on channel N. 

Returns the line number of the state¬ 
ment being executed at the time of a 
CTRL/C interrupt. 

Returns the value associated with 
the last encountered error if an ON 
ERROR GOTO statement appears in 
the program. 

Returns the line number at which the 
last error occurred if an ON ERROR 
GOTO statement appears in the 
program. 


(continued on next page) 
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Type 


Function 


Matrix Functions 
and Variables 
(Optional) 


Input/Output 


MAT Y = TRN(X) 
MAT Y = INV{X) 
Y = DET 

Y% = NUM 

Y% = NUM2 

Y% = RECOUNT 


Description 


Returns the transpose of the matrix X. 

Returns the inverse of the matrix X. 

Following an INV(X) function evalua¬ 
tion, the variable DET is equivalent to 
the determinant of X. 

Following input of a matrix, NUM con¬ 
tains the number of rows input or, in 
the case of a one-dimensional matrix, 
the number of elements entered. 

Following input of a matrix, NUM2 
contains the number of elements en¬ 
tered in that row. 

Returns the number of characters read 
following an input operation. Used 
primarily with non-file-structured 
devices. 


A.4 Summary of Statements 


The following summary lists in alphabetical order the general formats of 
BASIC—PLUS language statements and statement modifiers. For more 
detailed information, refer to the section or sections in the that 

describe the statement. 


Statement elements and their abbreviations are: 


variable or var 
line number 
expression or exp 
message 

condition or cond 
constant 

argument(s) or arg 

statement 

string 

protection 


Any legal variable (see Section 8.3.2 or A.1). 

Any legal line number (see Section 7.2.1). 

Any legal expression (see Section 8.4). 

Any combination of characters. 

Any relational or logical expression (see Sections 
8.4.3 and 8.4.4). 

Any integer constant (see Section 8.3.1). You do not 
have to include a % character. 

Dummy variable names. 

Any legal BASIC-PLUS statement. 

Any legal string constant, variable, function, or ex¬ 
pression. 

Any legal protection code, as described in the RSTS IE 
System Usefs Guide. 
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value(s) 


Any floating-point, integer, or string constant (see 
Section 8.3.1). 


list 


The legal list for the statement. 


dimension(s) 


One or two dimensions of an jirray, the maximum 
dimensions for the statement. 


Elements in angle brackets are necessary elements of the statement. 
Braces enclose a choice of elements, one of which is required for the state¬ 
ment. Square brackets enclose optional elements of the statement. 


A.4.1 Statements 


CHAIN-Section 13.10 


CHAIN <8triiig> ([LINE] <lme number>] 

100 CHAIN "PR0G3" LINE 75 
200 CHAIN 'PR0G3' LINE A 
440 CHAIN 'PR0G2' 

550 CHAIN PROGRAM* 2000 
570 CHAIN 'PR0G5' AX 


CHANGE - Section 10.2 


1 



<string variable > 
<array name> 


<array name> 
<8tring variable> 


CHANGE 


300 CHANGE A* TO X 

450 CHANGE STRING* TO ARRAYZ 

700 CHANGE ARRAYX TO STRING* 


CLOSE - Section 14.6 


CLOSE [#] <expre88ion> [,[#] <expres8ion> ,...] 


780 CLOSE «2X 

450 CLOSE «HX*«2X»*5X 

800 CLOSE «AZ + 6Z 

800 CLOSE «-CHANX IClose without writing buffer to file 
850 CLOSE *IX FOR IZ = IZ TO 12X IClose all channels 
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COMMENT - Section 7.4 


[ <8tatement> ]! <message> 

100 IThis is a coMwent 
150 PRINT IPerforw a CR/LF 


DATA - Section 9.2.3 


DATA <value list> 

1300 DATA 4.3f "STRING". lO» 1000. 1,45E9 


DEF*, single line - Sections 9.8, 10.6, 11.6 

DEF* FN<variable(arguments)> = <expre88ion(arguments)> 
120 DEF* FNA(X»Y*Z) = SOR<X''25i; + Y*2X + Z*2Z) 


DEF», multiple line - Section 13.1 


DEF* FN <variable{argument8)> 

<8tatements> 

[LET] FN <variable> = <expre8sion> 

FNEND 

300 DEF* FNF(MZ) {Factorial function 
310 IF MZ = OZ OR MZ = IZ & 

THEN FNF = IZ 8. 

ELSE FNF = MZ*FNF<MZ - IZ) 

320 FNEND 


NOTE 

BASIC-PLUS supports DEF as well as DEF* in single 
and multi-line functions for compatibility with earlier ver¬ 
sions. However, DEF* is preferred for compatibility with 
BASIC-PLUS-2. 
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DIM - Section 9.6 


DIM <variable(dimen8ion(8))> [,<variable(dimen8ion(8))> ,...] 

30 DIM A(20)» B$(6»5)» CX(99) 

DIM (Virtual Array) - Section 16.1 

DIM #<con8tant>,<8tringvar(dimension(s))> [ = <con8tant>] [,<var(dimension(8))> 
70 DIM » AtdOO) = 32X. B(50»50)» CX(30) 


END - Section 9.10 

END 

32767 END 


EXTEND — Section 7.5.1 

EXTEND 

10 EXTEND IProsraw in EXTEND mode 

FIELD-Section 17.4.1 

FIELD #<exp>,<expl> AS <8tring varl>[,<exp2> AS <8trmg var2>,...] 
700 FIELD *2%> lOX AS A$♦ 20X AS B*» 5X AS C$ 
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FOR - Section 9.5.1 


FOR <variable> = <expre8sion> TO <expre88ion> [STEP <expre8sion> ] 


200 FDR IX = 2X TO flOZ STEP 2Z 
300 FDR TZ = OZ TO T6X STEP IX 
400 FOR N = A TO <C + Sl)/A 


FOR-WHILE, FOR^UNTIL- Section 13.5 


FOR <variable> = <expre88ion> [STEP <expre88ion> ] 


while) 

UNTIL ) 


<condition> 


450 FOR 1=1. STEP 3. WHILE I < X 

470 FOR NX = 2Z STEP 4Z UNTIL NX > AZ OR NX * BX 

500 FOR B = 0. STEP B = 1. UNTIL B > Bl 


GET-Section 17.3 


GET #<e*P>|^» jjjECORD <e^> | .COUNT <exp> .USING <exp>j 

140 GET •2X» BLOCK SS. 

180 GET *4X. RECORD 50Z 


GOSUB - Section 9.9.1 


GOSUB <line number> 
190 GOSUB 2000 


GOTO - Section 9.3 


GrOTO <line number> 
100 GOTO 150 
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IF-THEN, IF-GOTO - Section 9.4 


I THEN <statement> 

THEN <line number> 

GOTO <line number> 

50 IF A > B OR B > C THEN PRINT "No" 

60 IF FNA(R) = B THEN 250 

75 IF L < X*2Z AND L <> 0, GOTO 1000 


IF-THEN-ELSE ~ Section 13.4 


IF <condition> 


THEN <statement> 
THEN <line nuinber> 
GOTO <line number> 


[ ELSE <statement> "1 
ELSE <line number>J 


200 IF B = A THEN PRINT 'EQUAL' ELSE PRINT 'NOT EQUAL' 
300 IF A «= N THEN 200 ELSE PRINT A \ STOP 
400 IF FNA(R) = B & 

THEN GOTO 2B0 & 

ELSE LET B = B + FNA(Rl) & 

\G0T0 1000 


INPUT-Sections 9.2.2, 10.3.2, 15.2 


INPUT [#<expre8sion>,] <variable list> 


100 INPUT A» 

200 INPUT "Enter your nawe'SA* 
300 INPUT i*lZ» ITEM$» PART 


INPUT LINE - Sections 10.3.3,15.2.3 

INPUT LINE [#<expre8sion>,] <8tring variable> 

300 INPUT LINE R» 

400 INPUT LINE «8Z» CUSTOMER$ 


KILL - Sections 5.4.2,14.8 


KILL <8tring> 

100 KILL 'OLD.DAT' 
200 KILL FILE.NAME* 
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LET - Section 9.1 


[LET] <variable(s)> = <expre8sion> 

110 LET AZ = 40Z 

120 B = 22. 

130 C# Fl» 0(0) = 0 'Multiple assignment 


LSET - Section 17.4.2 


LSET <8tring var> [,<string var>,...] = <string> 
100 LSET 8$ = 'XYZ' 


MAT Initialization - Section 12.5 


MAT <matrix name> 


ZER 

CON 

IDN 


((dimension(s))] 


100 DIH B(15»10)* A(IO). CZ<5) 

120 MAT CZ = CON 

130 MAT B = IDN<10*10) 

IflO MAT B = 2ER<N»M) 


MAT INPUT - Sections 12.4, 15.2.4 


MAT INPUT [#<expre8sion>,] <list of matrices> 


150 DIM B*(40>. F1Z(35) 

200 OPEN "DB2:MAT2.DAT" FOR INPUT AS FILE «3Z 
120 MAT INPUT «*3Z. B* . FIZ 


MAT PRINT-Sections 12.3, 15.1.3 


MAT PRINT [#<expre88ion>,] <matrix name> ^ | J 
150 DIM A(20) ♦ BZ(15 .30) 

200 MAT PRINT A. IPrint 20 elements, five on each line 
250 MAT PRINT BZ(10.25)5 IPrint 10-by-Z5 subset of BZ . 
300 MAT PRINT •2Z. A. IPrint on channel 2 


eacK ed 
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MAT READ - Section 12.2 


MAT READ <list of matrices> 

100 DIM A<20). 6»(32). CZdS.lO) 
200 MAT READ A» B»{25)» CX 


NAME-AS - Sections 5.2.2,14.7 


NAME <8triiig> AS <8tring> 

455 NAME "NONAME" AS “FILEl.DAT/PR:40" 

900 NAME 'DLl:MATRIX.DAT' AS 'MATAl.DAT<48>' 


NEXT - Section 9.5.1 


NEXT <variable> 

100 NEXT IZ 
200 NEXT N 


NOEXTEND - Section 7.5.1 


NOEXTEND 

50 NOEXTEND 
50 NO EXTEND 


ON ERROR GOTO - Section 13.7.1 


ON ERROR GOTO ( <line number> ] 


100 ON ERROR 
no ON ERROR 
no ON ERROR 


GOTO 9000 

GOTO 0 {Disables error-hand1 inS routine 
GOTO {Disables e r ro r-hand 1 routine 
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ON-GOSUB - Section 13.3 


ON <expression> GK)SUB <list of line nuinbers> 
230 ON FNC(M) GOSUB 2000» 2400» 3000 


ON-GrOTO - Section 13.2 


ON <expression> GOTO <list of line numbers> 
150 ON XZ GOTO 170# 570# 430# 300 


OPEN - Section 14.5 


OPEN <string> 


[{ 


FOR INPUT 
FOR OUTPUT 


!] 


AS FILE [#] <expression> 


[,REC0RDSIZE <exp> ] [,CLUSTERSIZE <exp> ] [,FILESIZE <exp> 


[,MODE <exp> ] 


100 OPEN 'LP:' FOR OUTPUT AS FILE I»B1Z 
200 OPEN “FOO^DAT" AS FILE #3% 

300 OPEN 'DM1SDATA 4 TR ' FOR INPUT AS FILE «10Z# RECORDSIZE 1024Z 


PRINT - Sections 9.2.1, 15.1 


PRINT [ [#<expre8sion>,] <list> ] 


130 PRINT fProduces CR/LF 
140 PRINT of output:”?!# A*I 

150 PRINT «2Z# 'OUTPUT TO DEVICE'5NZ 
ISO PRINT "Title: “?TITLE$# "Ref #"?R$ 


PRINT-USING-Section 15.1.2 

PRINT [#<expression>J USING <string>, <list> 

550 PRINT USING AA 

700 PRINT •7Z# USING B$# A#B#C 
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PUT - Section 17.3 


PUT #<exp> 



BLOCK <exp> 
RECORD <exp> 


I .COUNT <exp> .USING <exp> 


390 PUT COUNT BOX 

RANDOMIZE - Section 9.7.4 

RANDOM[IZE] 

40 RANDOMIZE 
100 RANDOM 

READ - Section 9.2.3 

READ <variable list> 

100 READ A» B»t FIX* B(1X)* R2 

REM - Section 7.4 

REM <message> 

100 REM - This prosram plays solitaire 

RESTORE - Section 9.2.4 

RESTORE 
100 RESTORE 

RESUME - Section 13.7.2 

RESUME [ <line nviinber> ] 

1000 RESUME 0 IResume at line where error occurred 
1000 RESUME lEquiualent to RESUME 0 
650 RESUME 200 !Resume at line 200 
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RETURN - Section 9.9.2 


RETURN 
375 RETURN 

RSET - Section 17.4.2 

RSET <8tring var> [,<8tring var>,...] = <8tring> 

250 RSET C$ = ••12345- 

sleep - Section 13,9 

SLEEP <expre88ion> 

260 SLEEP 20Z ISuspend Job for 20 seconds 

STOP - Sections 6.3.1, 9.11 

STOP 
180 STOP 

UNLOCK - Section 17.7 

UNLOCK #<expre8sion> 

500 UNLOCK *51 

UNTIL - Section 9.5.3 

UNTIL <condition> 

100 UNTIL LEN(A$) > OX 
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WAIT - Section 13.9 


WATT <expre88ion> 

520 WAIT AZ 

WHILE - Section 9.5.2 

WHILE <condition> 

30 WHILE X < Y 

A.4.2 Statement Modifiers 

FOR - Section 13.6.3. 

<statemeiit> FOR <variable> = <exp> TO <exp> [STEP <exp> ] 



175 LET B$(rZ> = C$(IX) FOR IX = IX TO JIX 
190 READ A(IX) FOR IX = OX TO 20X STEP JX 

IF-Section 13.6.1 

<8tatement> IF <condition> 

100 PRINT TX IF TX > TlX 

UNLESS - Section 13.6.2 

<8tatement> UNLESS <condition> 

350 PRINT A* UNLESS YX < OX 


A-18 Language Summary 




UNTIL - Section 13.6.5 


<8tatement> UNTIL <condition> 

1080 IF B <> 0 THEN A(IZ) = B UNTIL IZ > K 

WHILE - Section 13.6.4 

<8tatement> WHILE <condition> 

230 LET A(IZ) = FNX(IZ) WHILE A < A5.5 
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A.5 Reserved Keywords 


BASIC-PLUS statement, function, variable, and option names are reserved 
keywords. This means that you cannot use them for your own variable or 
function names. 

Table A-1 lists all language elements that are reserved for DIGITAL- 
supplied versions of BASIC—PLUS and BASIC—PLUS—2. Do not use any of 
the listed words as the name of a variable or function. 

Table A—1; Reserved Keywords 


ABS 

DATA 

FSPS 

NOECHO 

ABS% 

DATES 

FSSS 

NONE 

ACCESS 

DEF 

GE 

NOREWIND 

ALLOW 

DELETE 

GET 

NOSPAN 

ALTERNATE 

DENSITY* 

GO 

NOT 

AND 

DESC 

GOSUB 

NUL$ 

APPEND 

DET 

GOTO 

NUM 

AS 

DIF$ 

GT 

NUM$ 

Ascn 

DIM 

HT 

NUM1$ 

ATN 

DIMENSION 

IDN 

NUM2 

BACK 

DUPLICATES 

IF 

ON 

BEL 

ECHO 

IMP 

ONECHR 

BLOCK 

EDIT$ 

INDEXED 

ONERROR 

BLOCKSIZE 

ELSE 

INPUT 

OPEN 

BS 

END 

INSTR 

OR 

BUCKETSIZE 

EQ 

INT 

ORGANIZATION 

BUFFER 

EQV 

INV 

OUTPUT 

BUFSIZ 

ERL 

KEY 

PEEK** 

BY 

ERN$ 

KILL 

PI 

CALL 

ERR 

LEFT 

PLACE$ 

CCPOS 

ERROR 

LEFTS 

POS 

CHAIN 

ERT$ 

LEN 

PRIMARY 

CHANGE 

ESC 

LET 

PRINT 

CHANGES 

EXIT 

LF 

PROD$ 

CHR$ 

EXP 

LINE 

PUT 

CLOSE 

EXTEND** 

LINPUT 

QUO$ 

CLUSTERSIZE** 

FF 

LOG* 

RAD$ 

COM 

FIELD 

LOG 

RANDOM 

COMMON 

FILE 

LOGIO 

RANDOMIZE 

COMP% 

FILES 

LSET 

RCTRLC 

CON 

FILESIZE 

MAGTAPE 

RCTRLO 

CONNECT 

FILL 

MAP 

READ 

CONTIGUOUS 

FILLS 

MAT 

RECORD 

COS 

FILL% 

MID 

RECORDSIZE 

COUNT 

FIND 

MIDS 

RECOUNT 

CR 

FIX 

MODE 

REF 

CTRLC 

FIXED 

MODIFY 

RELATIVE 

CVT$$ 

FNEND 

MOVE 

REM 

CVT$% 

FNEXIT 

NAME 

RESET 

CVT$F 

FOR 

NEXT 

RESTORE 

CVT%$ 

FORMATS 

NOCHANGES 

RESUME 

CVTF$ 

FROM 

NODUPLICATES 

RETURN 


(continued on next page) 
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Table A—1; Reserved Keywords (Cent.) 



RIGHT 

SQR 

TAPE 

USING 

RIGHT$ 

STATUS 

TASK 

VAL 

END 

STEP 

TEMPORARY 

VAL% 

RSET 

STOP 

THEN 

VALUE 

SCRATCH 

STR$ 

TIME 

VARIABLE 

SEG% 

STREAM 

TIME! 

VIRTUAL 

SEQUENTIAL 

STRING! 

TO 

VT 

SGN 

SUB 

TRM! 

WAIT 

SI 

SUBEND 

TRN 

WHILE 

SIN 

SUBEXIT 

UNDEFINED 

WINDOWSIZE 

SLEEP 

SUM! 

UNLESS 

WRITE 

SO 

SWAP% 

UNLOCK 

WRKMAP 

SP 

SYS** 

UNTIL 

XLATE 

SPACE! 

TAB 

UPDATE 

XOR 

SPAN 

SPEC 

TAN 

USEROPEN 

ZER 

*Reserved word, included for compatibility with DECSYSTEM 20 
**Supported on RSTS/E only 
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Appendix B 
Command Summary 


Table B-1 briefly describes the BASIC-PLUS keyboard monitor com¬ 
mands. For details on the syntax and use of these commands, see Part I of 
this manual and the RSTS/E System User's Guide. (Commands marked 
with an asterisk (*) are described in the RSTS/E System User’s Guide.) 
Table B-2 summarizes control characters and terminal keys. 


Fable B-1: ] 

BASIC-PLUS Commands 

Command 

Description 

APPEND 

Merges the contents of a previously saved source program with the cur¬ 
rent program. 

The BASIC-PLUS APPEND command differs from the DCL APPEND 
command. The DCL APPEND command appends one file to the end of 
another. See the RSTSIE DCL U8er*s Guide for more information. 

ASSIGN* 

Reserves an I/O device for use by a job. Only the job that issues the 
ASSIGN command can use the device. ASSIGN also assigns a logical 
name to a device» assigns an account to the @ character, and sets a 
default protection code. 

The BASIC-PLUS ASSIGN command differs from the DCL ASSIGN 
command. The DCL ASSIGN command only assigns a logical name to a 
device. See the RSTS/E DCL User's Guide for more information. 

BYE* 

Logs you out; closes and saves any open files. 

After you type BYE and press the RETURN key, the system displays: 

Confirm: 

You have five options: 

? Displays help on valid responses to the "Confirm” prompt. 

Y Normal logout. 

N No logout; cancels the BYE command. 

I Delete files individually before logging out. 

F Fast logout. 

To request one of these options in the BYE command, type BYE, a slash, 
and one of the valid responses (BYE/F, for example). 


(continued on next page] 
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Table B-1: BASIC-PLUS Commands (Cont.) 


Command 

Description 

CAT 

CATALOG 

Displays your file directory. The default device is the system disk» but 
you can specify another device after the word CAT or CATALOG. 

CCONT 

For privileged users. Same as CONT command, but detaches the job 
from the terminal. 

COMPILE 

Saves a translated image of the current program in a disk file. The 
default file name is the current program name; the default file t3npe is 
.BAC. 

CONT 

Continues execution of the current program after execution of a STOP 
statement. 

DEASSIGN* 

Releases a device for use by other jobs. DE ASSIGN also releases a logi> 
cal name for a device, cancels the association between an account and 
the @ character, and changes the current default protection code back 
to the system default. The system performs an automatic DEASSIGN 
when you enter the BYE command. 

The BASIC-PLUS DEASSIGN command differs from the DCL 
DEASSIGN command. The DCL DEASSIGN command only releases a 
logical name for a device. See the RSTS/E DCL User's Guide for more 
information. 

DELETE 

Removes one or more lines from the program in memory. After the word 
DELETE, type the line number of the line to be deleted or two line 
numbers separated by a dash (-). You can specify several single lines or 
ranges of lines. Use commas to separate line numbers or line number 
ranges. Typing DELETE with no line numbers deletes all lines from 
your current program. 

The BASIC-PLUS DELETE command differs from the DCL DELETE 
command. The DCL DELETE command deletes a file from a directory. 
See the RSTS/E DCL User's Guide for more information. 

EXIT 

Clears memory and returns control to the job keyboard monitor. 

EXTEND 

Puts BASIC-PLUS in EXTEND mode. You can write and run programs 
that include EXTEND mode features. 

HELLO* 

Tells RSTS/E that you want to log in. The system prompts you for a 
project-programmer number and password. You can also use HELLO 
to attach a detached job to the terminal or change accounts without 
logging out. 

KEY 

Reenables terminal echo after a TAPE command. (Use this command 
only with ASR33 terminals that have a low-speed paper-tape reader.) 

Press the LINE FEED key before entering the KEY command in case 
the last line input did not end with a carriage return/line feed. 

Use the LINE FEED or ESCAPE key (not RETURN) to enter the KEY 
command. The system does not treat a carriage return character as a 
delimiter when the terminal is in tape mode. 


(continued on next page) 
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Table B-1: 

BASIC-PLUS Commands (Cont) 

Command 

Description 

LENGTH 

Returns the length of your current program in IK increments, along 
with its maximum allowed size. For example, if the current program 
is between 6K and 7K and the maximum size is 16K, BASIC-PLUS 
displays: 

7(16)K of memory used 

LIST 

Displays all or part of the program currently in memory. The word LIST 
by itself displays your entire program. LIST followed by one line num¬ 
ber displays that line; LIST followed by two line numbers separated by a 
dash (-) displays the lines between and including the indicated lines. 
You can display several single lines or ranges of lines. Use commas to 
separate line numbers or line number ranges. 

LISTNH 

Same as LIST, but does not print the header that contains the program 
name and current date and time. 

NEW 

Clears your memory area, names a new program, and lets you enter a 
new program at the terminal. The default program name is NONAME. 

NOEXTEND 

Puts BASIC-PLUS in NOEXTEND mode. EXTEND mode features 
are no longer available unless the program contains an EXTEND 
statement. 

OLD 

Retrieves a saved source program from disk and places it in memory. By 
default, OLD retrieves NONAME.BAS in your account on the public 
structure. 

REASSIGN* 

Transfers control of a device to another job. 

RENAME 

Changes the name of the program currently in memory. 

The BASIC-PLUS RENAME command differs from the DCL RENAME 
command. The DCL RENAME command renames files. See the RSTS IE 
DCL User^s Guide for more information. 

REPLACE 

Copies the source program currently in memory into a disk file. The 
default file name is the current program name; the default file type is 
.BAS. Unlike the SAVE command, REPLACE replaces an existing file 
with the same name. 

RUN 

Executes the program in memory. If you type a file specification after 
the word RUN, the system loads the file from disk, translates it if neces¬ 
sary, and executes it. 

RUNNH 

Executes the program in memory without printing the header that con¬ 
tains the program name and current date and time. You can use 
RUNNH to run the current program only. 

SAVE 

Copies the source program currently in memory into a disk file. The 
default file name is the current program name; the default file t 3 rpe is 
.BAS. SAVE does not replace an existing file with the same name. 

SCALE 

Sets the scale factor to a specified value. When you do not specify a 
value, SCALE displays the current and pending scale factors. 


(continued on next page) 
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Table B-1; BASIC-PLUS Commands (Cent.) 


Command 

Description 

TAPE 

Disables terminal echo while the terminal’s low-speed reader reads a 
paper tape into the system. (Use this command only with ASR33 termi¬ 
nals that have a low-speed paper-tape reader.) 

Use the NEW command before the TAPE command. NEW causes 
BASIC-PLUS to expect input of a source program. After entering the 
TAPE command, insert the tape in the low-speed reader and set the 
reader’s control switch to START. 

UNSAVE 

After you type the TAPE command, the system ignores RUBOUT char¬ 
acters and does not treat carriage return characters as delimiters. The 
program is not printed on the terminal as the system reads it, but error 
messages are printed. 

Use the KEY command to reenable terminal echo when you finish using 
the low-speed reader. 

Deletes a file from a directory. The default file name is your current 
program name; the default file type is .BAS. 
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Table B~2: Control Characters and Terminal Keys 


Key 

Function 

CTRL/C 

Halts execution of the current program and returns control to the job 
keyboard monitor. Echoes on the terminal as ”*0”. 

CTRL/0 

Stops and restarts terminal output while a program is running. 

CTRL/Q 

Resumes terminal output suspended by CTRL/S while a program is 
running. You can use CTRL/Q only if the terminal STALL characteris¬ 
tic is set. 

CTRL/R 

Redisplays the current terminal line. 

CTRL/S 

Suspends terminal output while a program is running. You can use 
CTRL/S only if the terminal STALL characteristic is set. 

CTRL/U 

Deletes the current terminal line. CTRL/U does not erase characters 
from the screen. Instead, it echoes and moves the cursor to the next 

line. 

CTRL/Z 

Is an end-of-file marker. 

DELETE 

Erases the last character typed. 

ESCAPE 

ALTMODE 

Sends a typed line to the system for processing. Echoes on your terminal 
as a and does not perform a carriage return/line feed. 

FORM FEED 
CTRL/L 

Sends a typed line to the system for processing. Performs a form feed 
operation on the terminal. 

LINE FEED 

Continues the current program line on another terminal line. Performs 
a line feed/carriage return operation. 

NO SCROLL 

It is recommended that you use the ampersand (&)/RETURN key 
combination instead of the LINE FEED key to continue the current 
program line on another terminal line. You can use the ampersand/ 
RETURN key combination only in EXTEND mode. 

Performs the same function as CTRL/S and CTRL/Q on a VTIOO termi¬ 
nal. The terminal STALL characteristic must be set. 

RETURN 

Sends a typed line to the system for processing. Performs a carriage 
return/line feed operation on the terminal. 

RUBOUT 

Erases the last character typed and echoes erased characters inside 
backslashes. 

TAB 

Moves the cursor to the next tab stop on the terminal line. By default, 
tab stops are eight spaces apart. 
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Appendix C 
Error Messages 


C.1 Interpretation of Error Messages 

Messages in RSTS/E are generated both for BASIC—PLUS errors and 
RSTS/E errors. These messages are called RSTS/E error messages and are 
described as one set. The BASIC—PLUS errors cover conditions that occur 
during translation and at run time, such as a violation of the syntax rules 
(?Syntax error) and referencing an element of an array beyond the defined 
limits (?Subscript out of range). The RSTS/E errors involve operating sys¬ 
tem conditions, such as failing to locate the file or account specified (?Can’t 
find file or account) and requesting the hardware to perform a function for 
which it is not ready (?Device hung or write locked). Tables C—4 and C-6 
describe the RSTS/E error messages. 

In most cases, if you are not trapping errors (that is, an ON ERROR GfOTO 
statement is not in effect), BASIC-PLUS stops running the program. It 
prints the error message and the line number of the BASIC-PLUS state¬ 
ment that was being executed when the error occurred. The following sam¬ 
ple printout shows the procedure: 

10 OPEN 'Z' FOR INPUT AS FILE IX 

RUNNH 

?Can't find file or account at line 10 
Ready 


As the Ready prompt indicates, control returns to the system. 

One exception to this procedure occurs when you execute an INPUT state¬ 
ment at the job’s console terminal and error trapping is not in effect. The 
system generates the error message and executes the statement again, as 
shown in the following sample printout: 

10 ON ERROR GOTO 0 \ INPUT 'INTEGER VALUE'lAZ 

RUNNH 

INTEGER VALUE? C 

ZData format error at line 10 

INTEGER VALUE? 
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With error trapping disabled at line 10, an invalid response to the INPUT 
statement cavises the system to print the error message, clear the error 
condition, and execute the statement again. 

Associated with each message is an error variable called ERR. Whenever 
an error occurs with trapping in effect, the system checks the error variable 
(which is a decimal number in the range 0 to 127). An error with a number 
between 1 and 70 causes the system to transfer control to the line number 
indicated in the ON ERROR GOTO statement. The system does not print 
the error message. Your program is able to check the ERR variable and 
perform a recovery procedure. 

If the error number is between 71 and 127, the system does not transfer 
control to the recovery routine but prints the message and returns control 
to the system. (Error number 0 is reserved to identify the system installa¬ 
tion name.) 

Because a BASIC-PLUS program can recover from certain errors, this 
appendix lists errors in two categories —recoverable and nonrecoverable. 
The recoverable error messages are in ascending order of their error num¬ 
bers. A program can use these error numbers to differentiate errors. Non¬ 
recoverable errors are in alphabetical order without error numbers, 
because a program cannot use these numbers in an error handling routine. 

The first character position of each message indicates the severity of the 
error. Table C—1 describes this standard. 


Table C-1: Severity Standard in Error Messages 


Character 

Severity 

Meaning 

% 

Warning 

Execution of the program can continue but may not gen¬ 
erate the expected results. 

? 

Fatal 

Execution cannot continue unless you remove the cause of 
the error. No space or tab is allowed after the question 
mark. 


Information 

A message beginning with neither a question mark nor a 
percent sign is for information only. 


In the error message descriptions in Tables C-4 and C-5, the abbreviations 
shown in Table C—2 denote special characteristics of the error. 

Table C—2: Special Abbreviations for Error Descriptions 


Abbreviation 

Meaning 

c 

SPR 

Continue. If an ON ERROR GK)TO statement is not in effect, execu¬ 
tion continues but with the conditions described. 

Software Performance Report. This error should occur only imder the 
conditions described. If it occurs under any other conditions, you 
should document the conditions under which the error occurred and 
have the appropriate person at your site send an SPR to DIGITAL. 
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If an error occurs in a program with no error trapping in effect, shown as 
"C” in Table C—2, BASIC-PLUS prints the error message and line number 
but continues rimning the program. The following sample printout shows 
the procedure: 

100 ON ERROR GOTO 0 \ AX = 32708. 

200 PRINT AX 

RUNNH 

XInteser error at line 100 
0 

Ready 


The attempt to compute a value outside the range for integers generated an 
"%Integer error” at line 100. After BASIC-PLUS prints the error message, 
processing continues but with the conditions described in the error mean¬ 
ing. BASIC-PLUS substitutes 0 for the erroneously computed value. 

The number of RSTS/E error messages is restricted to 127. Because of this 
restriction, certain error messages have multiple meanings. The specific 
meaning of an error message depends on the operation you are performing 
when the error condition occurs. For example, if the system attempts a file 
access and the designated file cannot be located, RSTS/E generates the 
"?Can’t find file or account” error (ERR=5). That same error condition, 
however, applies to other, generically similar access operations. 

Thus, if a program attempts to send a message to another program and the 
system cannot find the proper entry in the system table of eligible 
receivers, RSTS/E returns error number 5. Though the second failure does 
not involve a file access error, it too is classified as an access failure. 

Certain RSTS/E errors, although classified as user-recoverable, cannot be 
trapped by a program. Table C-3 lists these errors. 

Table C-3: Non-Trappable Errors in Recoverable Class 


ERR 

Message Printed 

34 

?Reserved instruction trap 

36 

?SP stack overflow 

37 

?DiBk error during swap 

38 

?Memory parity failure 


These errors involve special conditions that your program cannot control 
and that should not occur on a normal system. For example, the "?Disk 
error during swap” error indicates a hardware problem. The system does 
not return control to the program. The error condition itself, however, can 
be either transient or recurring. 

Bring these errors to the attention of your system manager for further 
investigation. These errors are recoverable in the strict sense that the 
monitor can take corrective action. However, the BASIC—PLUS run-time 
system does not return control to your program. 
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Table C-4: User-Recoverable Error Messages 


ERR 

Message Printed 

Meaning 

0 

(system installation name) 

The error code 0 is associated with the 
system installation name. System pro¬ 
grams use this to print identification 
lines. 

1 

?Bad directory for device 

1. The directory of the device referenced 
is in an unreadable format. 



2. The magnetic tape label format on 
tape differs from the system-wide de¬ 
fault format, the current job default 
format, or the format specified in the 
OPEN statement. Use the ASSIGN 
command to set the correct format 
default or change the format specifi¬ 
cation in the MODE option of the 
OPEN statement. 

2 

?Illegal file name 

1. The file name or type specified is not 
acceptable. It contains unacceptable ' 
characters or violates the file specifi¬ 
cation format. 



2. The CCL command to be added 
begins with a number or contains a 
character other than A through Z, 0 
through 9, or at sign (@). 

3 

?Accoimt or device in use 

1. The account to be deleted has one or 
more files and must be zeroed before 
being deleted. 



2. Reassigning or dismounting of the 
device cannot be done because the de¬ 
vice is open or has one or more open 
files. 



3. The run-time system to be deleted is 
in use. 



4. Output to a pseudo keyboard cannot 
be done unless the device is in KB 
wait state. 



5. An echo control field cannot be de¬ 
clared while another field is active. 



6. The CCL command to be added 
already exists. 

4 

?No room for user on device 

You have already used the allowed stor¬ 
age space; the device as a whole is too full 
to accept further data. 

5 

?Can’t find file or account 

Either the file or account number speci¬ 
fied was not found on the device specified, 
or the CCL command to be deleted does 
not exist. 


(continued on next page) 
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Table C-4: User-Recoverable Error Messages (Gout.) 



ERR 

Message Printed 

Meaning 

6 

?Not a valid device 

The device specification supplied is not 
valid for one of the following reasons: 

1. The unit number or its type is not 
configured on the system. 

2. The specification is logical and 
untranslatable because a physical de¬ 
vice is not associated with it. 

7 

?I/0 channel already open 

You tried to open one of the twelve I/O 
channels that the program had already 
opened. (SPR) 

8 

?Device not available 

The specified device exists on the system, 
but you cannot assign or open it for one of 
the following reasons: 

1. The device is currently reserved by 
another job. 

2. The device requires privileges for 
ownership that you do not have. 

3. The system manager has disabled the 
device or its controller. 

4. The device is a keyboard line for 
pseudo keyboard use only. 

9 

?I/0 channel not open 

You tried to perform I/O on one of the 
twelve channels that the program has not 
previously opened. 

10 

?Protection violation 

You cannot perform the requested opera¬ 
tion because the operation is illegal (such 
as input from a line printer) or because 
you do not have the privileges necessary 
(such as deleting a protected file). 

11 

?End of file on device 

You tried to perform input beyond the 
end of a data file, or a BASIO-PLUS 
source file is called into memory that does 
not contain an END statement. 

12 

?Fatal system I/O failure 

An I/O error has occurred on the system 
level. You have no guarantee that the 
last operation has been performed. This 
error is caused by a hardware condition. 
Report such occurrences to the system 
manager. 

13 

?Data error on device 

One or more characters may have been 
transmitted incorrectly due to a parity 
error, bad punch combination on a card, 
or similar error. 





(continued on next page) 
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Table C-4: User-Recoverable Error Messages (Cont.) 


ERR 

Message Printed 

Meaning 

14 

?Device himg or write locked 

Check the hardware condition of the de¬ 
vice you are requesting. Possible causes 
of this error include a line printer out of 
paper or high-speed reader being off-line. 

16 

?Keyboard WAIT exhausted 

Time that the WAIT statement requests 
has been exhausted with no input 
received from the specified keyboard. 

16 

?Name or account now exists 

Either you tried to rename a file with the 
name of a file that already exists, or 
the system manager tried to insert an 
account number that is already in the 
system. 

17 

?Too many open files on unit 

Only one open DECtape output file is per¬ 
mitted per DECtape drive. Only one open 
file per magnetic tape drive is permitted. 

18 

?Illegal SYS() usage 

Illegal use of the SYS system function. 

19 

?Disk block is interlocked 

The requested disk block segment is al¬ 
ready in use (locked) by some other user. 

20 

?Pack IDs don’t match 

The identification code for the specified 
disk pack does not match the identifica¬ 
tion code already on the pack. 

21 

?Disk pack is not mounted 

No disk pack is moimted on the specified 
disk drive. 

22 

TDisk pack is locked out 

The disk pack specified is mounted but is 
temporarily disabled. 

23 

?Illegal cluster size 

The specified cluster size is unacceptable. 
The cluster size must be a power of 2. For 
a file cluster, the size must be equal to or 
greater than the pack cluster size and 
must not be greater than 256. 

For a pack cluster, the size must be equal 
to or greater than the device cluster size 
and must not be greater than 16. The de¬ 
vice cluster size is fixed by t 3 rpe. 

24 

?Disk pack is private 

You do not have access to the specified 
private disk pack. 

25 

?Disk pack needs 'CLEANing’ 

Nonfatal disk mounting error; run the 
ONLCLN system program. 

26 

?Fatal disk pack mount error 

Fatal disk mounting error. Disk cannot 
be successfully mounted. 

27 

?I/0 to detached keyboard 

I/O was attempted to a hung-up dataset 
or to the previous, but now detached, con¬ 
sole keyboard for the job. 
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Table C-4: User-Recoverable Error Messages (Cont.) 


ERR 

Message Printed 

Meaning 

28 

?Programmable trap 

A CTRL/C was typed while an ON 
ERROR GOTO statement was in effect 
and programmable CTRL/C trapping 
was enabled. 

29 

?Corrupted file structure 

Fatal error in CLEAN operation. 

30 

?E>evice not file structured 

An attempt is made to access a device 
other than a disk, DECtape, or magnetic 
tape device as a file-structured device. 
This error occurs, for example, when you 
attempt to get a directory listing of a non¬ 
directory device. 

31 

?Illegal b 3 rte count for I/O 

This error has two possible causes: 

1. The buffer size you specified in the 
RECORDSIZE option of the OPEN 
statement or the COUNT option of 
the PUT statement is not a multiple 
of the block size of the device you are 
using for I/O, or is illegal for the 
device. 

2. You tried to run a compiled file that 
has improper size due to incorrect 
transfer procedure. 

32 

?No buffer space available 

You accessed a file and the monitor re¬ 
quired one small buffer to complete the 
request, but there is no buffer available. 

If the program is sending messages, two 
conditions are possible. The first occurs 
when a program sends a message and the 
receiving program has exceeded the pend¬ 
ing message limit. The second occurs 
when a sending program attempts to send 
a message and a small buffer is not avail¬ 
able for the operation. 

33 

?Odd address trap 

This error occurs when you attempt to 
address nonexistent memory or an odd 
address with the PEEK function. If you 
get this error for any other reason, report 
it to your system manager. 

34 

?Reserved instruction trap 

An attempt is made to execute an illegal 
or reserved instruction or an FPP instruc¬ 
tion when floating-point hardware is not 
available. (See discussion at beginning of 
appendix.) 

35 

?Memory management violation 

You specified an illegal monitor address 
in the PEEK function. If you get this 
error for any other reason, report it to 
your system manager. 


(continued on next page) 
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Table C-4: User-Recoverable Error Messages (Cont.) 


ERR 

Message Printed 

Meaning 

36 

?SP stack overflow 

An attempt was made to extend the hard¬ 
ware stack beyond its legal size. (See 
discussion at beginning of appendix.) 
(SPR) 

37 

?Di8k error during swap 

A hardware error occurs when your job is 
swapped into or out of memory. The con¬ 
tents of your job area are lost, but the job 
remains logged into the system and 
is reinitialized to run the NONAME 
program. Report such occurrences to 
the system manager. (See discussion at 
beginning of appendix.) 

38 

?Memory parity failure 

A parity error was detected in the mem¬ 
ory occupied by this job. (See discussion 
at beginning of appendix.) 

39 

?Magtape select error 

When access to a magnetic tape drive was 
attempted, the selected imit was found to 
be off line. 

40 

?Magtape record length error 

When performing input from magnetic 
tape, the record on magnetic tape was 
longer than the buffer designated to han¬ 
dle the record. 

41 

?Non-res run-time system 

The run-time system referenced has not 
been loaded into memory and is therefore 
nonresident. 

42 

?Virtual buffer too large 

Virtual array buffers must be 512 bytes 
long. 

43 

?Virtual array not on disk 

A nondisk device is open on the channel 
on which the virtual array is referenced. 

44 

?Matrix or array too big 

Memory array size is too large. 

45 

?Virtual array not yet open 

You tried to use a virtual array before 
opening the corresponding disk file. 

46 

?Illegal I/O channel 

You tried to open a file on an I/O channel 
outside the range of the integer numbers 

1 to 12. 

47 

?Line too long 

The buffer overflows because of an at¬ 
tempt to input a line longer than 255 
characters. (This includes any line termi¬ 
nator.) 

48 

%Floating point error 

You tried to use a computed floating¬ 
point number outside the range lE-38 
<n<lE38 excluding zero. If no transfer to 
an error handling routine is made, zero is 
returned as the floating-point value. (C) 


(continued on next page) 
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Table C-4: User-Recoverable Error Messages (Cont.) 



ERR 

Message Printed 

Meaning 

49 

%Argument too large in EXP 

Acceptable arguments are within the 
approximate range -89<arg< + 88. The 
value returned is zero. (C) 

50 

%Data format error 

A READ or INPUT statement detected 
data in an illegal format. For example, 
1..2 is an improperly formed number; 
1.3 is an improperly formed integer; 
’’HELLO” ’THERE” is an illegal string. 
(C) 

51 

%Integer error 

You tried to use a computed integer 
outside the range -32768<n<32767. For 
example, you tried to assign to an integer 
variable a floating-point number outside 
the integer range. If no transfer to an 
error handling routine is made, zero is 
returned as the integer value. (C) 

62 

?Illegal number 

Integer overflow or underflow, or float¬ 
ing-point overflow. The range for integers 
is -62768 to 4-32767; for floating-point 
numbers, the upper limit is 1E38. (For 
floating-point underflow, the ’’^Floating 
point error” (ERR = 48) is generated.) 

53 

%lllegal argument in LCXj 

Negative or zero argument to LOG func¬ 
tion. Value returned is the argument as 
passed to the fimction. (C) 

54 

%Imaginary square roots 

You tried to take the square root of a 
number less than zero. The value 
returned is the square root of the absolute 
value of the argument. (C) 

55 

?Sub8cript out of range 

You tried to reference an array element 
beyond the number of elements created 
for the array when it was dimensioned. 

56 

?Can*t invert matrix 

You tried to invert a singular or nearly 
singular matrix. 

57 

?Out of data 

The DATA list was exhausted and a 
READ requested additional data. 

58 

?ON statement out of range 

The index value in an ON-GOTO or 
ON-GOSUB statement is less than one or 
is greater than the number of line num¬ 
bers in the list. 

59 

?Not enough data in record 

An INPUT statement did not And enough 
data in one line to satisfy all the specified 
variables. 

60 

?Integer overflow, FOR loop 

The integer index in a FOR loop at¬ 
tempted to go beyond 32766 or below 
-32767. 





(continued on next page) 
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Table C-4: User-Recoverable Error Messages (Cont.) 



ERR 

Message Printed 

Meaning 

61 

%Division by 0 

Attempt in your program to divide some 
quantity by zero. If no transfer is made to 
an error handling routine, the result is 0. 
(C) 

62 

?No run-time system 

The run-time system referenced has not 
been added to the system list of run-time 
systems. 

63 

?FIELiD overflows buffer 

You tried to use FIELD to allocate more 
space than exists in the specified buffer. 

64 

?Not a random access device 

You tried to perform random access I/O 
to a nonrandom access device. 

65 

?niegal MAGTAPE() usage 

Improper use of the MAGTAPE function. 

66 

?Missing special feature 

Your program uses a BASIC-PLUS fea¬ 
ture not present on the given installation. 

67 

?Illegal switch usage 

This error has two possible causes: 

1. A CCL command contains an error in 
an otherwise valid CCL switch. (For 
example, use of the /SI:n switch with¬ 
out a value for n or a colon; or specifi¬ 
cation of more than one of the same 
type of CCL switch.) 

2. A file specification switch is not the 
last element in a file specification or 
is missing a colon or an argument. 




Table C-5: Nonrecoverable Error Messages 


Message Printed 

Meaning 

?Arguments don’t match 

Arguments in a function call do not match, in 
number or in t 3 rpe, the arguments defined for the 
function. 

?Bad line number pair 

Line numbers specified in a LIST or DELETE com¬ 
mand were formatted incorrectly. 

?Bad number in PRINT-USING 

Format specified in the PRINT-USING string can¬ 
not be used to print one or more values. 

?Can’t CONTinue 

Program was stopped or ended at a spot from which 
execution cannot be resumed with CONT or 
CCONT. 

?Data type error 

Incorrect usage of floating-point, integer, or string 
variable or constant where some other data type 
was necessary. 


(continued on next page) 
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Table C-5: Nonrecoverable Error Messages (Cont.) 


Message Printed 

Meaning 

?DEF without FNEND 

A second DEF statement was encountered in the 
processing of a user function without an FNEND. 

?End of statement not seen 

Statement contains too many elements to be pro¬ 
cessed correctly. 

?Error text lookup failiure 

An I/O error occurred while the system was 
attempting to retrieve an error message. Possible 
cause could be that the device containing the sys¬ 
tem error file (ERR.SYS) is off-line or the system 
error file contains a bad block. 

?£xecute only file 

Attempt was made to add, delete, or list a state¬ 
ment in a translated (.BAG) file. 

?Expression too complicated 

This error usually occurs when parentheses have 
been nested too deeply. The depth allowed depends 
on the individual expression. 

?File exists-RENAME/REPLACE 

A file of the name specified in a SAVE command 
already exists. To save the program with the name 
specified, use REPLACE, or use RENAME followed 
by SAVE. 

?FNEND without DEF 

A FNEND statement was encoimtered in your pro¬ 
gram before a DEF statement was seen. 

?FNEND without function call 

An FNEND statement was encountered in your 
program before a function call was executed. 

?FOR without NEXT 

A FOR statement was encountered in your program 
without a corresponding NEXT statement to termi¬ 
nate the loop. 

?lllegal conditional clause 

?Illegal DEF nesting 

Incorrectly formatted conditional expression. 

The range of one function definition crosses the 
range of another function definition. 

?lllegal dummy variable 

One of the variables in the dummy variable list of 
user-defined functions is not a legal variable name. 

?Illegal expression 

Double operators, missing operators, mismatched 
parentheses, or some similar error was found in an 
expression. 

?Illegal FIELD variable 

?Illegal FN redefinition 

?Illegal function name 

The FIELD variable specified is unacceptable. 

Attempt was made to redefine a user function. 

Attempt was made to define a function with a func¬ 
tion name of incorrect format. 

?Illegal IF statement 

?Illegal in immediate mode 

Incorrectly formatted IF statement. 

You entered a statement in immediate mode that 
can only be executed as part of a program. 

?Illegal line number(s) 

Line number reference outside the range 
l<n<32767. 
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Table C-5: Nonrecoverable Error Messages (Cont.) 


Message Printed 

Meaning 

?Illegal mode mixing 

?Illegal statement 

String and numeric operations cannot be mixed. 

Attempt was made to execute a statement that did 
not translate without errors. 

?Illegal symbol 

An unrecognizable character was encoimtered. For 
example, a line consisting of a # character. 

?lllegal verb 

The verb portion of the statement cannot be recog¬ 
nized. 

%Incon8i8tent function usage 

A function is defined with a certain number of argu¬ 
ments but is referenced elsewhere with a different 
number of arguments. Fix the reference to match 
the definition and reload the program to reset the 
function definition. 

%Inconsistent subscript lise 

A subscripted variable is being used with a differ¬ 
ent number of dimensions from the number with 
which it was originally defined. 

?Literal string needed 

A variable name was used where a numeric or char¬ 
acter string was necessary. 

?Matrix dimension error 

Attempt was made to dimension a matrix to more 
than two dimensions, or an error was made in the 
syntax of a DIM statement. 

?Matrix or array without DIM 

A matrix or array element was referenced beyond 
the range of an implicitly dimensioned matrix. 

?Maximum memory exceeded 

This error has two possible causes: 

1. During an OLD operation, the job’s private 
memory size maximum was reached. 

2. While running a program, the system required 
more memory for string or I/O buffer space, 
and the job’s private memory size maximum 
or the system maximiun (16K words for 
BASIC-PLUS) was reached. 

?Modifier error 

This error has two possible causes: 

1. Attempt was made to use one of the statement 
modifiers (FOR, WHILE, UNTIL, IF or 
UNLESS) incorrectly. 

2. An OPEN statement modifier, such as a 
RECORDSIZE, CLUSTERSIZE, FILESIZE, or 
MODE option, is not in the correct order. 

?NEXT without FOR 

A NEXT statement was encountered in your pro¬ 
gram without a previous FOR statement. 

?No logins 

Message printed if the system is full and cannot 
accept additional users, or if further logins are dis¬ 
abled by the system manager. 


(continued on next page) 
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Table C-6: Nonrecoverable Error Messages (Cont.) 


Message Printed 

Meaning 

?Not enough available memory 

An attempt was made to load a nonprivileged com¬ 
piled program that is too large to run given the job’s 
private memory size maximum. The program must 
be made privileged in order to expand above a pri¬ 
vate memory size maximum, or the system mana¬ 
ger must increase the job’s private memory size 
maximum to accommodate the program. 

?Number is needed 

A character string or variable name was used 
where a number was necessary. 

?1 or 2 dimensions only 

Attempt was made to dimension a matrix to more 
than two dimensions. 

?ON statement needs GrOTO 

A statement beginning with ON does not contain a 
GOTO or GOSUB clause. 

Please say HELLO 

Message printed by the LOGIN system program. A 
user who was not logged into the system has typed 
something other than a legal, logged-out command. 

?Plea8e use the RUN command 

A transfer of control (as in a GOTO, GOSUB or 
IF-GOTO statement) cannot be performed from 
immediate mode. 

?PRINT~USING buffer overflow 

Format specifled contains a field too large to be 
manipulated by the PRINT-USING statement. 

7PRINT-USING format error 

An error was made in the construction of the string 
used to supply the output format in a PRINT¬ 
USING statement. 

?Program losb-Sorry 

A fatal system error caused your program to be lost. 
This error can indicate hardware problems or use of 
an improperly compiled program. See Section C.2 
for more information. 

?Redimensioned array 

Usage of an array or matrix within your program 
has caused BASIC—PLUS to redimension the array 
implicitly. 

7RESUME and no error 

A RESUME statement was encountered where 
no error had occurred to cause a transfer into an 
error handling routine with the ON ERROR GOTO 
statement. 

7RETURN without GOSUB 

RETURN statement is encountered in your pro¬ 
gram when a previous GOSUB statement was not 
executed. 

%SCALE factor interlock 

1. You set a new scale factor and then executed a 
program that was translated using a different 
scale factor. The program runs, but BASIC-PLUS 
uses the scale factor in effect when the program 
was translated. To cause BASIC-PLUS to trans¬ 
late the program with the new scale factor, use 
REPLACE and OLD. 


(continued on next page) 
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Table C-5: Nonrecoverable Error Messages (Cont.) 


Message Printed 

Meaning 

%SCALE factor interlock (Cont.) 

2. You set a new scale factor and then entered an 
immediate mode statement. Immediate mode 
statements are always translated using the cur¬ 
rent scale factor. The new scale factor will take 
effect when you use the NEW or OLD command 
or run a program from its source file. 

See Section 11.10.2 for more information. (C) 

TStatement not found 

Reference is made in the program to a line number 
that is not in the program. 

Stop 

STOP statement was executed. You can usually 
continue program execution by t 3 rping CONT and 
the RETURN key. 

?String is needed 

A number or variable name was used where a char¬ 
acter string was necessary. 

?Syntax error 

BASIC-PLUS statement was incorrectly formatted. 

?Too few arguments 

The function has been called with a number of 
arguments not equal to the number defined for the 
function. 

?Too many arguments 

A user-defined function can have up to five argu¬ 
ments only. 

?Undefined function called 

BASICJ-PLUS interpreted some statement compo¬ 
nent as a function call for which there is no defined 
function (system or user). 

?What? 

You entered a command or immediate mode state¬ 
ment that BASIC-PLUS cannot process. Illegal 
verb or improper format error most likely. 

TWrong math package 

Program was compiled on a system with either the 
two-word or four-word math package, and an 
attempt is made to run the program on a system 
with the opposite math package. Recompile the pro¬ 
gram using the math package of the system on 
which it will be run. 


C.2 The “?Program Lost-Sorry” Error 

The "?Program lost-Sorry” error occurs when BASIC-PLUS tries to run a 
program and cannot. BASIC-PLUS clears the job image from memory and 
returns control to the user. If possible, BASIC-PLUS prints a second mes¬ 
sage that provides more information about what caused the program to be 
lost. In several cases, however, only the "?Program losb-Sorry” message is 
printed, and the system manager must check the error log to determine the 
cause. Always report a ”?Program lost-Sorry” message and its associated 
message (if printed) to your system manager. 
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The ”?Program lost>-Sorry” error has four possible causes: 

1. A checksum error occurs on a .BAG file. (A checksum error is usually 
the result of a hardware problem.) 

2. An unrecoverable disk error occurs while BASIC—PLUS is reading a 
.BAG file. 

3. BASIC—PLUS tries to load a .BAG file of incorrect size. 

4. BASIC—PLUS tries to nm a file whose stored version number does not 
match the current BASIC-PLUS run-time system’s version number. 

You can often recover by recompiling the program from its source file and 
running it again. To recompile the program: 

1. Use the OLD command to translate the program from its source file. 
OLD places the translated program in memory. 

2. Use the COMPILE command to create a new .BAG file that contains 
the translated image. 

The next four sections describe each of the possible causes in more detail. 

C.2.1 Checksum Error on a .BAG File 

A "checksum” is a numeric quantity that is used to detect errors. When you 
save a translated program in a disk file with the COMPILE command, 
BASIC-PLUS computes a checksum and stores it in the file. BASIC-PLUS 
computes another checksum when it loads the .BAG file from disk. An error 
occurs if the computed and stored checksums do not match. 

If the checksums are not equal, BASIC—PLUS produces an error to be 
logged by the RSTS/E monitor, returns the "?Program lost-Sorry” error to 
the user, and aborts program execution. 

Checksum errors are usually caused by a disk error. The disk error may 
have occurred when you created the .BAC file or it may have occurred 
while BASIC—PLUS was reading the .BAC file into memory. 

You can usually recover by recompiling the program and running it again. 

C.2.2 Unrecoverable Disk Error Reading a .BAC File 

The "?Program lost-Sorry” error also results when an unrecoverable disk 
error occiirs while BASIC—PLUS is loading a .BAC file into memory. Unre¬ 
coverable disk errors can result from bad disk blocks, dust, problems with 
the disk drive, or a transient hardware problem in the disk subsystem. 
Sometimes these errors produce a warning message such as "?Disk eiror 
during swap”, which is logged in the system error logging file. 

Recompiling the program may correct the problem. Be sure to report the 
problem to your system manager. 
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C.2.3 Incorrect .BAC File Size 

A .BAC file must be between 2K and 16K words (inclusive). In addition, the 
number of blocks in the file must be an integer that is one less than a 
multiple of 4. 

If the size of the .BAC file does not follow these rules, BASIC-PLUS prints 
two messages when it tries to load the file into memory: "?Program 
lostr-Sorry” and "?Illegal byte count for I/O”. These errors are not logged in 
the system error logging file. 

To correct the problem, recompile the program. 

C.2.4 Unmatched Version Numbers 

When you use COMPILE to save a translated program, BASIC-PLUS 
writes the current version number of the BASIC-PLUS run-time system 
into the .BAC file. When BASIC—PLUS runs or chains to a .BAC file, it 
checks the version number stored in the file against the version number of 
the run-time system being used. If the version numbers do not match, the 
”?Program losl^Sorry” error results. 

Consult the RSTS/E Release Notes to find out whether recompilation of 
current programs is necessary for a new version of BASICJ-PLUS. 

C.3 Reporting Software Problems 

Report problems with DIGITAL software to your system manager. Your 
system manager will determine whether the problem needs to be reported 
to DIGITAL. 


C-16 Error Messages 




Appendix D 

BASIC-PLUS Character Set 





BASIC-PLUS programs are composed of: 

• The letters A through Z in both upper- and lowercase 

• The digits 0 through 9 

• Spaces 

• Tabs 

• The special symbols and keys listed in Table D-1 
Table D-1: Special Symbols and Keys 


Symbol or Key 

Use 

$ 

Suffix for string variables and functions; see Section 8.3 and Chapter 
10. 

% 

Suffix for integer variables and functions; see Section 8.3 and 
Chapter 11. 


Indicates the decimal point in floating-point numbers and numeric 
strings; see Section 8.3. The period is a valid character in EXTEND 
mode variable names; see Section 8.3.2.1. The period also separates 
the file name and type in a file specification; see the RSTS IE System 
User's Guide. 

> 

Delimiter for string constants (text strings); see Section 8.3.1.3. 

») 

Delimiter for string constants (text strings); see Section 8.3.I.3. 

1 

Begins a comment; see Section 7.4. 

\ 

Separates multiple statements on one program line; see Section 7.3.1. 

* 

Separates multiple statements on one program line; accepted for 
compatibility with previous versions of BASIC-PLUS. The backslash 
(\) is the preferred character. 


(continued on next page) 
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Table D-1: Special Symbols and Keys (Cont.) 


Symbol or Key 

Use 

# 

Indicates an I/O channel number; see Section 14.5. The # is also a 
formatting character in the PRINT-USING statement; see Section 
15.1.2, 

9 

Formatting character in PRINT statement; see Section 9.2.1.2. The 
comma is also part of the S 3 nitax for several BASIC-PLUS state¬ 
ments. For example, you use commas between variable names in the 
INPUT statement and between options in statements such as OPEN, 
GET, and PUT. 

9 

Formatting character in PRINT statement; see Section 9.2.1.2. 

& 

Part of the &/RETURN key combination, which indicates that 
a statement is continued on the next terminal line; legal only in 
EXTEND mode. See Section 7.3.2. 

(EE) 

Indicates that a statement is continued on the next terminal line; see 
Section 7.3.2. (The &/RETURN key combination is the preferred 
way to continue a statement.) 

@ 

Indicates the assignable account; see the RSTS/E System User^s 
Guide. 

() 

Specify how operations are to be performed in expressions; see 
Section 8.4.5. Parentheses also enclose function arguments (see 
Chapter 9) or a project-programmer number (see the RSTS /E System 
User^s Guide). 

[] 

Enclose a project-programmer number; see the RSTS/E System 
Use/s Guide. 

+ - 
♦ / " 

Arithmetic operators; see Section 8.4.1. 


Replacement operator; see Section 9.1. The equal sign also means 
'’equal to” in numeric and string relational expressions; see Section 
8.4.3. 

= = 

Means "approximately equal to” in numeric relational expressions; 
see Section 8.4.3. 

< 

Relational "less than” operator; see Section 8.4.3. 

> 

Relational "greater than” operator; see Section 8.4.3. 

< > 

Relational "not equal to” operator; see Section 8.4.3. 
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Table D-2: ASCII Character Codes 


Ascn 


Remarks 

Decimal 

Octal 

Character 

0 

000 

NUL 

Null, FILL character 

1 

001 

SOH 

CTRL/A 

2 

002 

STX 

CTRL/B 

3 

003 

ETX 

CTRL/C 

4 

004 

EOT 

End of transmission, CTRL/D 

5 

005 

EN(5 

CTRL/E 

6 

006 

ACK 

CTRL/F 

7 

007 

BEL 

Bell, CTRL/G 

8 

010 

BS 

Backspace, CTRL/H 

9 

Oil 

HT 

Horizontal tab, CTRL/I 

10 

012 

LF 

Line feed, CTRL/J 

11 

013 

VT 

Vertical tab, CTRL/K 

12 

014 

FF 

Form feed, page, CTRL/L 

13 

015 

CR 

Carriage return, CTRL/M 

14 

016 

SO 

CTRL/N 

15 

017 

SI 

CTRL/0 

16 

020 

DLE 

CTRL/P 

17 

021 

DCl 

CTRL/Q*, XON 

18 

022 

DC2 

CTRL/R 

19 

023 

DC3 

CTRL/S**, XOFF 

20 

024 

DC4 

CTRL/T 

21 

025 

NAK 

CTRL/U 

22 

026 

SYN 

CTRL/V 

23 

027 

ETB 

CTRL/W 

24 

030 

CAN 

CTRL/X 

25 

031 

EM 

CTRL/Y 

26 

032 

SUB 

CTRL/Z, end of file 

27 

033 

ESC 

Escape*** 

28 

034 

FS 


29 

035 

GS 


30 

036 

RS 


31 

037 

US 


32 

040 

SP 

Space or blank 

33 

041 

J 

Exclamation mark 

34 

042 

H 

Quotation mark 

35 

043 

# 

Number sign 

36 

044 

$ 

Dollar sign 

37 

045 

% 

Percent sign 

38 

046 

& 

Ampersand 

39 

047 

f 

Apostrophe 

40 

050 

( 

Left parenthesis 

41 

051 

) 

Right parenthesis 

42 

052 

* 

Asterisk 

43 

053 

-f 

Plus sign 

44 

054 

9 

Comma 

45 

055 

- 

Minus sign or hyphen 


(continued on next page) 
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Table D-2: ASCII Character Codes (Cont.) 


ASCII 


Remarks 

Decimal 

Octal 

Character 

46 

056 

, 

Period or decimal point 

47 

057 

/ 

Slash 

48 

060 

0 

Zero 

49 

061 

1 

One 

50 

062 

2 

Two 

51 

063 

3 

Three 

52 

064 

4 

Four 

53 

065 

5 

Five 

54 

066 

6 

Six 

55 

067 

7 

Seven 

56 

070 

8 

Eight 

57 

071 

9 

Nine 

58 

072 

: 

Colon 

59 

073 

> 

Semicolon 

60 

074 

< 

Left angle bracket, "less than” sign 

61 

075 

= 

Equal sign 

62 

076 

> 

Right angle bracket, "greater than” sign 

63 

077 

? 

Question mark 

64 

100 

@ 

At sign 

65 

101 

A 

Uppercase A 

66 

102 

B 

Uppercase B 

67 

103 

C 

Uppercase C 

68 

104 

D 

Uppercase D 

69 

105 

E 

Uppercase E 

70 

106 

F 

Uppercase F 

71 

107 

G 

Uppercase G 

72 

110 

H 

Uppercase H 

73 

111 

I 

Uppercase I 

74 

112 

J 

Uppercase J 

75 

113 

K 

Uppercase K 

76 

114 

L 

Uppercase L 

77 

115 

M 

Uppercase M 

78 

116 

N 

Uppercase N 

79 

117 

0 

Uppercase 0 

80 

120 

P 

Uppercase P 

81 

121 

Q 

Uppercase Q 

82 

122 

R 

Uppercase R 

83 

123 

S 

Uppercase S 

84 

124 

T 

Uppercase T 

85 

125 

U 

Uppercase U 

86 

126 

V 

Uppercase V 

87 

127 

w 

Uppercase W 

88 

130 

X 

Uppercase X 

89 

131 

Y 

Uppercase Y 

90 

132 

Z 

Uppercase Z 

91 

133 

[ 

Left square bracket 

92 

134 

\ 

Backslash 

93 

135 

] 

Right square bracket 

94 

136 

^ or t 

Circumflex, up arrow, caret 

95 

137 

or_ 

Underscore or buck arrow 
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Table D-2: ASCII Character Codes (Cont.) 


ASCII 



Decimal 

Octal 

Character 

Remarks 

96 

140 


Grave accent 

97 

141 

a 

Lowercase a 

98 

142 

b 

Lowercase b 

99 

143 

c 

Lowercase c 

100 

144 

d 

Lowercase d 

101 

145 

e 

Lowercase e 

102 

146 

f 

Lowercase f 

103 

147 

g 

Lowercase g 

104 

150 

h 

Lowercase h 

105 

151 

i 

Lowercase i 

106 

152 

j 

Lowercase j 

107 

153 

k 

Lowercase k 

108 

154 

1 

Lowercase 1 

109 

155 

m 

Lowercase m 

110 

156 

n 

Lowercase n 

111 

157 

0 

Lowercase o 

112 

160 

P 

Lowercase p 

113 

161 

q 

Lowercase q 

114 

162 

r 

Lowercase r 

115 

163 

8 

Lowercase s 

116 

164 

t 

Lowercase t 

117 

165 

U 

Lowercase u 

118 

166 

V 

Lowercase v 

119 

167 

w 

Lowercase w 

120 

170 

X 

Lowercase x 

121 

171 

y 

Lowercase y 

122 

172 

z 

Lowercase z 

123 

173 

{ 

Left brace 

124 

174 

1 

Vertical line 

125 

175 

} 

Right brace 

126 

176 

- 

Tilde 

127 

177 

DEL,RUBOUT 

Delete, rubout 

* CTRL/Q, or XON, 

resumes output if the TTYSET STALL characteristic is set. 

** CTRL/S, or XOFF, stops output if the TTYSET STALL characteristic is set. 

ALTMODE (ASCII 125) or PREFIX (ASCII 126) keys, which appear on some termi¬ 

nals, are translated internally into ESCAPE. 
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Appendix E 

Hints for BASIC-PLUS/BASIC-PLUS-2 
Compatibility 


The following list contains guidelines for writing BASIC-PLUS programs 
that are compatible with BASIC—PLUS-2. Most of the guidelines also 
appear in the manual, in the description of the topic they pertain to. 

1. Write programs in EXTEND mode. 

2. Use the ampersand/RETURN combination, not the LINE FEED key, 
for continuation lines. The ampersand should appear either one space 
after the last significant character on the line or after one tab on other¬ 
wise blank lines. 

3. Delimit all string constants with matching single (’) or double (”) 
quotation marks. 

4. Include semicolons between strings and other items in PRINT state¬ 
ments. For example, enter: 

20 PRINT "Customer Address"; A* 

You cannot use implied semicolons in BASlC-PLUS-2. The following 
PRINT statement is not compatible: 

20 PRINT "Customer Address" A$ 

5. Use only one prompting message in an INPUT statement. For example: 

50 INPUT "Enter your name and account number” 

The following INPUT statement, which contains two prompting mes¬ 
sages, is not compatible with BASIC—PLUS-2: 

50 INPUT “Enter your name”? N$» “Enter your account number“fA 

6. Use DEF*, not DEF, for user-defined functions. 
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7. Do not use parentheses when you define or call functions with no argu¬ 
ments. Use: 

30 DEF* FNAZ 

Do not use: 

30 DEF* FNAZO 

8. Use the CCPOS function instead of the POS function. CCPOS performs 
the same function in BASIC-PLUS and BASIC—PLUS-2. POS performs 
a different fvmction in BASIC-PLUS and BASIC-PLUS-2. 

9. When you write CHAIN statements, always include the optional key¬ 
word LINE. Use the form: 

CHAIN <8tring> LINE <line number> 

Do not use the form: 

CHAIN <string> <line number> 

10. When you use arrays, always place the DIM statement before the first 
reference to the array it defines. For virtual arrays, place the DIM 
statement before the OPEN statement. 

11. To disable an error handling subroutine, use the statement: 

100 ON ERROR GOTO 0 

Do not use: 

100 ON ERROR GOTO 

12. Always include a RESUME statement in an error handling subroutine. 

13. Always include the number sign (#) when specifying a channel num¬ 
ber. For example: 

500 CLOSE *2X,*aX 

14. In the PRINT—USING statement, do not use $$ and ** in the same 
format field. 

15. Do not use the COUNT option, the BLOCK option, or the USING option 
in GET statements. You cannot use these options with GET in 
BASIC-PLUS-2. 
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Appendix F 
Programming Hints 


This appendix is a collection of programming hints for the advanced 
BASIC-PLUS user: 

• Section F.l tells how to optimize BASIC—PLUS programs to reduce stor¬ 
age space and execution time. 

• Section F.2 describes how to reduce disk access time. 

• Section F.3 describes how to manipulate strings efficiently. 

• Section F.4 explains in detail how the CVT fimctions convert data 
between numeric and string format. You will need this information if you 
plan to read files with block I/O that were created using a different I/O 
method. 

• Section F.5 shows you the algorithm that BASIC-PLUS uses to access 
data in virtual array files. You might find this information useful if you 
need to access a virtual array file using block I/O. 

F.l Optimizing BASIC-PLUS Programs 

By optimizing your use of statements and variables, you can write pro¬ 
grams that use less storage space and execute more quickly. 

Most of the time, these two goals are mutually exclusive: you can save 
space at the expense of time or vice versa. You need to decide which 
approach best fits your needs. If you can optimize both space and time, the 
entire system and your program benefit. 

F.1.1 Optimizing Statement Formats 

When BASIC-PLUS translates a soxirce program into executable code, it 
creates structures called "statement headers.” Statement headers contain 
information that the system needs to execute the program. 
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BASIC-PLUS creates a statement header for each line number in a pro¬ 
gram. In addition, certain statements always produce a statement header, 
regardless of where in a line they occur. These statements are DATA, DEF, 
DEF*, DIM, FNEND, FOR, NEXT, WHILE and UNTIL. 

You can save statement header space by placing multiple statements on a 
single program line. Statements that require a statement header shovild be 
first on a line where possible. When you write multi-statement lines, use a 
separate text line for each statement. Your program will be easier to read. 

You can also save statement header space by placing comments on the 
same line as statements. A REM statement and a comment with its own 
line number each require a 12-byte statement header. 

F.1.2 Using Variables Efficiently 

Assigning a temporary variable sometimes saves array addressing space. 
Consider: 


10 FOR II = II TO NI 8. 

\ S = S + X(II) i 
\ S2 = S2 + X(II) ♦ X(ll) 
20 NEXT II 


You can decrease the number of bytes required for storage by assigning a 
simple variable T equal to the subscripted variable X(I%): 


10 FOR II = II TO NI & 
\ T = X(II) & 

\ S = S + T 8. 

\ S2 = S2 + T * T 
20 NEXT II 


Besides using less storage space, this example also executes faster than 
the first one because BASIC-PLUS does not have to recalculate array 
addresses. 

Individual variable names are often more economical than arrays because 
they require less overhead. If you use arrays, always dimension them with 
a DIM statement. 

For efficiency, calculate quantities once and reuse them. For example: 

10 D = S0R(5-2.-4. » A » 0/21 * A 8. 

\ PRINT -B/2I * A + Di -B/2I * A - D 


This line is more efficient than: 


10 D = SQR(B*2.-a. » A * 0/21 * A 8. 

\ PRINT -B/2I # A + S0R<B*2.-a. * A » 0/21 » A 5 8. 

\ PRINT -B/2I * A - S0R(B‘2.-4. * A * 0/21 * A 
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Use intermediate variables only when necessary. For example: 

20 A = B + C 8. 

\ D = A + E & 

\ F = D + G 

Unless you plan to use A and D later in the program, condense this line to: 
20F=B+C+E+G 

Integers use less storage space than floating-point numbers, and integer 
arithmetic is much faster than floating-point arithmetic. Thus, you should 
use integer variables and constants where possible. Be sure to include the 
% suffix. 

Use integer variables for array subscripts. Also use integers in FOR-NEXT 
loops with STEP values that are whole numbers in the range -32767% to 
32766%. 

Because of the way BASIC-PLUS stores variables, using variables with the 
same names but different data types (for example. A, A% and A$) saves 
space. However, this use of variables makes a program difficult to read and 
maintain. 

Because BASKD—PLUS uses integers for logical operations, integer varia¬ 
bles do not have to be compared to zero explicitly. For example: 

30 IF MX <> 0 THEN 80 

BASIC—PLUS interprets a nonzero value as true; thus, you can write this 
statement as: 

30 IF MX THEN 80 

Combine this technique with the IF statement modifier for a statement 
that uses even less storage space: 

30 GOTO 80 IF MX 

F.1.3 Using Constants Efficiently 

Avoid ambiguous constants. When you specify constants, make them expli¬ 
citly floating-point or integer by including a period (.) or a percent sign (%). 
Use integer constants for whole numbers in the range -32767% to 32767%. 

BASIC—PLUS optimizes commonly used constants. The integer constants 
0% and 1% and certain floating-point constants produce fewer bytes of 
translated code than other constants. 

Each reference to an integer constant produces three bytes of translated 
code. But each reference to the integer constant 0% or 1% produces only one 
byte of translated code. 
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Each reference to a two-word floating-point constant produces seven bytes 
of translated code; each reference to a four-word floating-point constant 
produces eleven bytes of translated code. However, each reference to the 
floating-point constants 0. or 1. produces only one byte of translated code. 
In addition, a reference to one of the following floating-point constants 
produces three bytes of translated code; 

• Any power of two 

• Any whole number from 2. to 256. 

• A power of ten up to 1000. 

Both positive and negative values are optimized in all cases. 

F.1.4 Statement Modifiers 

Implied FOR loops use less memory and execute faster than FOR-NEXT 
loops. Consider: 

10 FOR IX = IX TO lOX & 

\ RX = R*2X & 

\ NEXT IX 

The FOR and NEXT statements each produce a statement header. A FOR 
statement modifier, which produces only one statement header, creates a 
more efficient loop: 

10 RX = RX‘2X FOR IX = IX TO lOX 

This implied FOR loop uses about 30% less memory than the FORr-NEXT 
loop. 

Where possible, use the WHILE and UNTIL statement modifiers instead of 
loops and IF—THEN statements. Consider: 

10 IF XX < LX THEN XX = XX * XZ 8, 

\ GOTO 10 

You can perform this operation more efficiently with the statement: 

10 XX = XX * XZ WHILE XX < LX 

F.1.5 Optimizing Statement Structure 

When using multiple IF statements, use IF-THEN-ELSE instead of 
IF-THEN. Consider: 

100 IF XX = WZ THEN 250 

110 IF XX = AZ THEN 300 

120 IF XX = KX THEN 500 

130 IF XX = LX THEN 600 
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The following IF—THEN—ELSE statement uses 35% less memory than the 
previous example: 

100 IF XZ = WZ THEN 250 ELSE & 

IF XT. = AX THEN 300 ELSE & 

IF XX = KX THEN 500 ELSE &c 
IF XX = LX THEN BOO 


To compare a variable to a continuous range of values, use the ON-GOTO 
statement instead of the IF statement. For example: 


100 ON XX - 3X GOTO 250# 300# 500# BOO 


This statement is more efficient than the following IF-THEN-ELSE 
statement: 


100 IF XX = 4X THEN 250 ELSE & 

IF XX = 5X THEN 300 ELSE & 

IF XX = BX THEN 500 ELSE &c 
IF XX = 7X THEN BOO 


You can use a similar technique with strings. For example: 

80 XX = ASCII <A$) - B-aX & 

\ ON XX GOTO 100# 200# 300# 400 


These statements are more efficient than: 


80 IF A$ = "A" THEN GOTO 100 ELSE & 

IF Ai = "B" THEN GOTO 200 ELSE Be 

IF A$ = "C" THEN GOTO 300 ELSE & 
IF A$ = ”0" THEN GOTO 400 


Use the same method to test random string responses. For example, the 
following statement compares A$ with the letters X, K, B, and Y: 

80 ON INSTR<IX#"XKBY"#A$) + IX GOTO 100# 200# 300# 400# 500 


You can also save space by using subroutines instead of user-defined func¬ 
tions, but be sure to exit with RETURN (not CJOTO) statements. 

F.2 Decreasing Disk Access Time 

This section describes how to set up files to reduce disk access time. Some of 
these methods may require the assistance of your system manager. 

Open files at the beginning of a program and preextend them to their 
maximum size. In addition, preallocate scratch files and, when you are 
finished using them, close them instead of deleting them. You can then 
reuse them with OPEN FOR INPUT statements. These techniques save 
disk space, reduce fragmentation of the directory structure, and decrease 
access time. 
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Keep large, frequently used files on separate disks. When two files are 
often open at the same time, they should also be stored on separate disks. 
Keep production files and accounts separate from development and scratch 
files where possible. If you cannot keep development and scratch files on 
separate disks, keep them in separate accounts. 

Optimize file cluster sizes to further reduce disk access time. See Chapter 
14 of this manual, the RSTS/E System User's Guides and the RSTS/E 
Programming Manual for more information. The RSTSIE Programming 
Manual also describes other methods to save access time. 


F.3 Manipulating Strings Efficiently 

The following three algorithms truncate trailing blanks from a data record. 
The first two user-defined functions input a string and return the same 
string without trailing blanks and carriage return/line feeds. 

The slowest algorithm successively reassigns the argument until it ends 
with a nonblank character: 


1000 DEF* FNT$(X$) & 

\X$ = LEFT(X$ fLEN(X^)-r;f.) & 

WHILE RIGHT(X$ #LEN<X$) ) <= " " Sc 
AND LEN(X$)>0X 
1010 FNT$ = X$ 

1020 FNEND 


The following algorithm is much more efficient. It scans backwards until a 
nonblank character is found. Only one assignment is made. 


200 DEF* FNW$(X$) S: 

\G0T0 2010 IF MID(X$ tXX »1Z> >" “ Sc 

FOR XZ = LEN(X$) TO OZ STEP -IZ S: 
\ XZ = OZ 

2010 FNW$ = LEFT(X$#XZ) 

2020 FNEND 


The most efficient algorithm uses the data buffer directly, avoiding the 
assignment caused by the user-defined fimction. L% is the record length. 


3000 FOR KZ = LZ TO IZ STEP -IZ S: 

\FIELD #2Z» KZ-IZ AS L$ ♦ IZ AS L$ S: 
\IF L$>'' " THEN Sc 

FIELD nZXf KZ AS L$ S: 

\G0T0 3020 
3010 NEXT KZ Sc 
\LSET L% = 

3020 ! DONE 


F.4 Converting Numeric Data 

BASIC-PLUS stores numeric data in memory in either integer or floating¬ 
point format. When you use block I/O, you manipulate data in an inter¬ 
mediate I/O buffer. BASIC—PLUS lets you access the data in the buffer as 
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string data only. Thus, to process numeric data in your program, you must 
convert it from string to numeric format. After processing, you must con¬ 
vert the numeric data back to string data for output. 

BASIC-PLUS provides four CVT functions to perform the necessary data 
conversions. These functions are implemented for speed instead of logical 
ordering. They use stack operations to convert data and thus reverse the 
expected ordering of bytes. The CVT$% and CVT%$ functions, which con¬ 
vert data between string and integer format, transpose the high and low 
order bytes of the word. The CVT$F and CVTF$ functions, which convert 
data between string and floating-point format, transpose the high and low 
order bytes of each word and also reverse the ordering of the words. 

You are usually not aware of this reversal. When you manipulate data with 
block I/O, you use one CVT function when retrieving data from the I/O 
buffer and the related CVT function when loading data back into the I/O 
buffer for output. To illustrate. Figure F-1 shows the conversion of integer 
data by the CVT$% and CVT%$ functions. 

Figure F-1: CVT Conversion of Integer Data 
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The CVT%$ function reverses the byte order of the integer data word. The 
CVT$% reverses the byte order of the string data, thus returning the inte¬ 
ger to its correct byte order. 

You do need to be aware of this reversal, however, when you use block I/O 
to read data not written by block I/O. In this situation, the data read into 
the buffer is in the correct byte order. The CVT$% function reverses the 
correct byte order of the data in the buffer. You must use the SWAP% 
function, which swaps the high and low order bjdes of a word, to put the 
bytes back in the correct order. 

For example, suppose that you need to read the date from a DOS magnetic 
tape label using non-file-structured block I/O. The system writes the stan¬ 
dard PDP—11 internal representation of the date on a DOS magnetic 
tape label as a one-word integer value. To read the date using non-file- 
structured block I/O, you access it in two bytes of a buffer, which you define 
as a string variable (D$). You then move these two bytes into the integer 
variable D%, using the CVT$% function to convert the data from string to 
integer format. The CVT$% function reverses the order of the bytes, so you 
must use the SWAP% function to put them back in the correct order. For 
example: 

10 DX SMAPX(CUT$X(D») ) 
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You can then print the date with the DATE$ function: 

20 PRINT DATE${DX> 

A more complex reversal occxirs with floating-point data. Figure F-2 shows 
the conversion of two-word floating-point data by the CVTF$ and CVT$F 
functions. 

Figure F—2: CVT Conversion of Two-Word Floating-Point Data 
Floating-Point (two-word) String 



When converting a two-word floating-point value to a four-byte string, the 
CVTF$ function stacks the bytes in the reverse of their original order. The 
sign and exponent bits are not in the standard format. 

The same reversal occurs when the CVTF$ and CVT$F functions convert 
data between four-word floating-point and eight-byte string formats. 
Figure F-3 shows the results. 

Figure F-3: CVT Conversion of Four-Word Floating-Point Data 
Floating Point (four-word) String 
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As with integer data, you are not aware of this reversal when you manipu¬ 
late floating-point data with block I/O. You convert data from string to 
floating-point format using the CVT$F function; you convert the floating¬ 
point data back to string format using the related CVTF$ function. 


The reversal is evident, however, when you read data with block I/O 
that was not written using block I/O. Suppose, for example, that you read 
floating-point data from a virtual array file using block I/O methods. The 
virtual array processor does not convert data during input and output oper¬ 
ations. Thus, data read into an I/O buffer from a virtual array file using 
block I/O statements is in correct byte order. But the CVT$F fimction, 
which you must use to convert the data in the buffer from string to floating¬ 
point format, reverses the correct byte order. Thus, the resulting numeric 
data is bad. (The same problem occurs when you read integer data from a 
virtual array file using block I/O.) You can solve this problem by reversing 
the byte order of the data in the buffer before converting it. 


The following program creates a virtual array file that contains floating¬ 
point data. It then reads back the data using block I/O, reverses the b3rte 
order of the data in the buffer, and produces the floating-point representa¬ 
tion using the CVT$F function. 


100 OPEN '0IRT.DAT' FOR OUTPUT AS FILE «1Z & 

\ DIM «1» A(0) \ A»A(0) = RND * 1000.0 & 
SPRINT A 8c 
\ CLOSE IX 6c 

SOPEN 'VIRT.DAT' FOR INPUT AS FILE «2Z 
220 LZ = LEN<CVTF*(1.0) ) 8c 

\ GET *2X 
240 B$ = " 8c 

\ FOR IX = LZ - IZ TO OX STEP -IZ 
2G0 FIELD *2X. IZ AS Bl*» IX AS Bl$ 

280 B» = B* + Bl* 8c 

\ NEXT IZ 

300 PRINT CVT$F<B*)!'SHOULD EQUAL'iA 

327S7 CLOSE #1Z .i»2Z 8. 

\ END 


NOTE 

Reading a virtual array file using block I/O is not recom¬ 
mended because you lose the advantage of the automatic 
virtual array addressing mechanism. 


F.5 Accessing Algorithm for Virtual Arrays 

Fig^ure F-4 shows the algorithm that BASIC—PLUS uses to minimize the 
number of disk accesses needed in virtual array I/O. You might find this 
information useful if you need to access a virtual array file using block I/O. 
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Figure F-4: Virtual Array Accessing Algorithm 
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Glossary 


You will find the terms in this glossary throughout this manual. They are defined here to 
help you if you are unfamiliar with computer terminology. The definitions of these terms 
come from a number of sources and are not intended to be absolute. Where possible, the 
most common industry usage has been the basis for defining a term. 

Absolute value 

The size of a quantity expressed without regard for its sign; the magnitude of a 
numeric quantity. For example, the numeric quantities +15 and —15 each have an 
absolute value of 15. 

Alphanumeric 

A contraction of alphabetic-numeric; the set of characters that consists of upper- 
and lowercase letters and the digits 0 through 9. 

Argument 

An independent variable whose value determines the value of a function or opera¬ 
tion; the entity operated on by a command, function, or other instruction. For 
example: 

SOR (X) 

X is the argument of the SQR function. This function returns the square root of X. 

Arithmetic operator 

A symbol that represents one of the arithmetic operations, such as plus (+) for 
addition and minus (-) for subtraction. 


Array 

A series of items arranged in an orderly pattern; an ordered arrangement of elO' 
ments in one or two dimensions. 
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Array dimension 

One of the two possible array types; a list is a one-dimensional array, and a table 
is a two-dimensional array. 

Array eiement 

An item in an array. 

ASCii code 

An acronym for American Standard Code for Information Interchange; a standard¬ 
ized 7—bit code representing the 128 characters in which textual information is 
recorded. 

Backslash 

A character (\) used to separate statements when more than one statement appears 
on a program line. 

Base 10 

The decimal numbering system; indicates that there are ten symbols (0, 1, 2, 3,4, 
5, 6, 7, 8, and 9) allowed for each position in a decimal number; also Radix-10. 

Base 2 

The binary numbering system; indicates that there are two symbols (0 and 1) 
allowed for each position in a binary number; also Radix-2. 


BASIC 

Acronym for Beginner’s All-purpose Symbolic Instruction Code; a computer lan¬ 
guage designed for direct communication between terminals (users) and a 
computer. BASIC is a registered trademark of Dartmouth College. 


Binary 

A base 2 numbering system; a condition or property that has two possibilities. 

Binary digit 

One of the two symbols (0 or 1) in the binary numbering system; see also Bit. 

Binary number 

The representation of a value as one or more binary digits; binary numbers 
increase in value by a factor of 2 for each position to the left (for example, the 
binary number 100100 equals the decimal number 36). 

Bit 

A contraction of Binary digit; the smallest unit of binary information. 
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Blank 


One of the characters in a character set used to denote the presence of no informa¬ 
tion; a character used to print an empty space. 

Branch 

The transfer of control from the current instruction sequence within a program to 
an instruction other than the next sequential instruction. 


Buffer 

A temporary storage Eirea used to contain data. Buffers hold data being passed 
between processes or devices that operate at different times or speeds. 


Carriage return 

A keyboard operation that causes the terminal print head to return to the left 
margin; usually combined with a line feed to send input to the computer from a 
terminal. 


Central Processing Unit 

That portion of a computer system that controls the interpretation and execution 
of instructions; also CPU or main frame. 


Channel 

A path between two or more separate units along which information can flow. 


Character 

One of a set of elementary symbols; a human-readable symbol that can be an 
upper- or lowercase letter from A to Z, a number from 0 to 9, or a special symbol; a 
machine-readable symbol consisting of a group of binary digits. 


Character string 

A sequence of characters treated as a single unit by the computer. 


Circumflex 

A character (*) used to represent exponentiation. 


Code 

A set of S 3 rmbols and rules used to convert data from one representation to 
another; a system of correspondence between two units of information. The 
BASIC-PLUS language is a kind of code; so is the ASCII code used to store charac¬ 
ters on the PDP-11 computer. 
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Colon 


A character (;) used on some systems to separate statements when more than one 
statement appears on a line; see also Backslash. 

Command 

An order you give to a computer system that performs a predefined operation; the 
part of an instruction that specifies the operation to be performed. 

Comment 

Text that explains a particular program step but has no effect on program 
execution. 

Compile 

To save a translated BASIC-PLUS program in a disk file. (This term has a differ¬ 
ent meaning in other programming languages.) 

Computer 

A device capable of accepting information, processing that information, and 
providing a result; a device with self-contained memory that processes given infor¬ 
mation using prescribed operations and produces a result. 

Concatenate 

To unite in a series; to link together many items into one. In BASIC-PLUS, the 
plus sign (-1-) concatenates strings. 

Conditional branch 

A transfer of program control that takes place only when a prespecified condition 
is satisfied; see also Branch. 

Constant 

A quantity, value, or data representation that does not vary in value. 

Continuation 

A program state in which a program line is written across two or more terminal or 
text lines. 

Control character 

A special keyboard character that starts, changes, or stops an operation. For exam¬ 
ple, CTRL / O stops and restarts terminal output while a program is running. 

Control key 

A set of keyboard characters that causes a control action; a control key is usually 
the combination of the CTRL key and an alphabetic key, such as CTRL/C. 
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Counter 

A device or storage location that accumulates numbers and allows their value to 
increase or decrease; a device used to represent the number of occurrences of a 
certain event. 

CTRL/C 

A combination of the keyboard characters CTRL and C that, when pressed simul¬ 
taneously, halts program execution and returns you to command level. 


Cursor 

On a video terminal, a blinking white line or rectangle that marks the current 
position on the screen. 


Data 

Plural form of datum but commonly used as singular; any element of information 
that can be processed by a computer. 

Data element 

A series of data items within a related set of data. 

Data Item 

A single data unit within a data element or data set. 

Debugging 

The process of detecting, locating, and correcting any mistakes in a computer 
program; the process of testing a program for errors. 

Decimal number 

A number in the base 10 numbering system. The base 10 numbering system is 
composed of ten possible symbols (0 through 9) with each number position repre¬ 
senting that symbol times some power of 10. 

Decimal point 

The arithmetic symbol (.) appearing in decimal numbers that separates the whole 
and fractional parts of the number. 

Default 

An assumption made by a program when you do not provide a value. 

Default keyboard monitor 

The main keyboard you work in on a RSTS/E system. You enter the default 
keyboard monitor after you log in. 
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DELETE key 

A terminal keyboard character that erases t 5 T)ed data from memory. 


Delimiter 

A character (such as a comma or semicolon) that separates the different parts of a 
statement. An example of the use of delimiters is: 

10 PRINT "23*9=" f 23*9 » 9*23 


Device 

A mechanical unit; a peripheral unit usually used to perform input and output 
operations. 

Diagnostic 

Pertaining to the detection and isolation of program errors or hardware 
malfunctions. 

Dimension 

The range or size defined for an airay; a property whose number is used to 
uniquely determine the number of elements in a system of entities. 

Directory 

A device area that describes the layout of data on that device; a list of data con¬ 
tained in a file storage area in terms of names, length, and position. 


Disk 

A physical storage unit that stores data on rotating platters. 

Dummy variable 

An artificial value used to fulfill a condition without affecting an operation; a 
place holder. For example, the arguments you specify when you define a function 
with DEF* are dummy variables. 

Editing 

The process of modifying data, a program, or a file; the alteration of program 
format. 

E format 

Used in BASIC—PLUS to denote scientific notation. For instance, E-i-08 means 
"times ten to the eighth power” in this example: 

8.867E-I-08 = 8.867=*10"8 = 886700000.0 

This notation is necessary in BASIC-PLUS, which can print only 1 to 6 or 15 
digits (depending on the system). 
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Error 


A discrepancy between a real quantity and a theoretically correct quantity; a 
deviation from true value; a mistake. 

Error message 

A notice from the computer that indicates an error and usually contains recovery 
information; a program message indicating the presence of a mistake. 

Execution 

The process of performing an instruction; the series of steps a computer performs 
to arrive at a result. The RUN command executes programs. 


Exit 

A method for stopping a program; the point of departure from a routine. 

Exponent 

Indicates the number of times a value is to be multiplied by itself. For example, in 
the expression 2"3, which means 2*2*2, 3 is the exponent. 

Expression 

Any legal combination of data and operators; a source language combination of 
one or more variables and operators. 

Fatai error 

A program error that causes a permanent exit from the current operations; an 
error that must be corrected before execution can proceed. 

Field 

One or more data elements treated as a unit. A field is usually part of a larger 
logical unit called a record. 

File 

An ordered collection of data capable of storage; a collection of related information; 
data to be transferred from executing programs to external (nonmemory) devices. 

Format 

The arrangement of data; the specified organization of information on a device, 
file, or printout. 

Format error 

A mistake that occurs in the specified organization of data. 

Function 

In mathematics, the relationship between a dependent variable and one or 
more independent variables. In BASIC—PLUS, a named group of instructions. 
BASIC—PLUS provides built-in functions (such as SQR and CVT$$) to help you 
manipulate numbers and strings. You can also define your own functions. 
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Hardware 

The physical equipment or machinery that composes a computer system. 


Header 

The first part of a message; the initial portion of a message that acts as an identi¬ 
fying agent. 


Increment 

To add a quantity to another quantity; the quantity added. 


Index 

A nvimber or quantity used to identify a particular item within a group of items. 
For example, the numeric value of a character is an index in the XLATE function. 

Infinite loop 

A repetitive instruction set with no means of exit; a loop that continues to repeat. 

Initialize 

To set up initial conditions. For example, you might set a variable to be incre¬ 
mented in a loop to an initial value. 


Input 

Information to be processed by a computer. 


instruction 

A bit pattern that, when interpreted by the computer, directs it to perform an 
operation; a set of characters that defines an operation. You give instructions to 
BASIC-PLUS by entering commands and statements. BASIC—PLUS translates 
your commands and statements into a form that the computer can execute. 

Integer 

A whole munber containing no fractional or decimal part, such as 100. In 
BASIC-PLUS, you indicate an integer with a % suffix, for example, 100%. 

Interaction 

A process of mutual communication between a human user and a computer 
system. 

Interpreter 

In BASIC—PLUS, the part of the BASIC—PLUS run-time system that executes 
translated code. 
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Job 

The vinit that RSTS/E uses to keep track of everything you do from the time you 
log in to the time you log out. 

Job keyboard monitor 

The keyboard monitor that manages a job. You change your job keyboard monitor 
to work in different RSTS/E command environments. 


Keyboard 

A device that encodes data by converting a pressed character key into an electrical 
signal. 

Keyboard monitor 

The part of a run-time system that you communicate with. Each RSTS/E key¬ 
board monitor understands a set of commands. 

Keyword 

An essential word; a BASIC—PLUS verb that is a necessary element in the 
language. 

Language 

A systematic, unambiguous means for people to communicate with a computer; 
a set of representations, conventions, and associated rules used to convey 
information. 

Language processor 

Internal computer code that accepts data in one language and produces equivalent 
data in another language. 

Linefeed 

The keyboard operation that shifts from one line position to the same horizontal 
position on the next vertical line. 

Line number 

The beginning number of a program line used for identification; a numeric label. 

Log in 

To gain access to a computer system. 

Log out 

To leave a computer system. 
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Logic error 

A mistake in a program element that performs a decision-making fimction. For 
example, a GOTO statement that contains an incorrect line number is a logic 
error. 


Loop 

A sequence of instructions that is repeatedly executed until a terminating condi¬ 
tion occurs. 

Machine ianguage 

Binary instruction code that is directly readable by the computer. 

Magnetic tape 

A strip of material, usually plastic, that can store data in the form of magnetically 
polarized spots. 

Magnitude 

The absolute size or value of a number. 

Main program 

A computer program that controls all operations except those assigned to subpro¬ 
grams or subroutines. 

Math function 

A built-in routine designed to perform a mathematical computation. 


Matrix 

A general term for describing all the elements of a subscripted variable; an array. 

Memory 

A device on which data can be stored and from which it can be retrieved; internal 
computer storage. 

Muiti’Statement iine 

A single program line composed of two or more statements distinguished by a 
statement separator. For example: 

100 LET A = A+1 \ PRINT A 

Negative step 

A nonpositive loop increment index; a decremental loop. For example: 

FOR IZ=100’i; TO IX STEP -2X 

Nested ioop 

A loop embedded within another loop. 
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Nested parentheses 

A parenthetical operation embedded within another parenthetical operation in an 
expression. 

Nesting 

The process of including a routine or block of data within another routine or block 
of data. 


Nonprinting character 

A character in the computer code set for which there is no corresponding graphic 
symbol. For example, the carriage return character (ASCII code 13 decimal) is a 
nonprinting character. 


Nuii 

The character with the ASCII code 000; an absence of information. 

Nuii string 

A string without content; an empty string. 

Numeric variable 

A variable that reserves a location in memory for a nvuneric value. 

Octal 

Pertaining to the base 8 numbering system. 

One-dimensional array 

An array composed only of rows; a list. 

Operands 

The data on which an operation is to be performed. 

Operating system 

Software that controls the execution of computer programs and performs system 
functions; an integrated collection of programs that manage computer operations. 

Operation 

The action specified by a single computer instruction. 

Operator 

The symbol or code that indicates the action to be performed; the portion of an 
instruction that tells the computer what to do. For example, in BASIC-PLUS the 
plus sign (+) is an operator that adds numbers and concatenates strings. 
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Output 

Data that has been processed by the computer; the data produced as a result of 
transfer. 

Overflow 

A condition caused by a mathematical operation whose result exceeds the capacity 
of the computer; the portion of a result that cannot fit into a designated storage 
vmit. 


Paper tape 

A strip of paper that can store data in the form of punched holes. 

Parentheses 

Symbolic language elements used to indicate nesting in an expression; a method of 
nesting where expression interpretation proceeds from the innermost to outermost 
level. 


Peripheral device 

Equipment that is separate or separable from the computer’s processing unit; 
usually equipment that provides communication between the computer and its 
environment. Common peripheral devices are terminals, line printers, disks, and 
magnetic tapes. 


Pointer 

An instruction used to indicate the location of data. 


Print 

A process that causes the display or output of data. 


Printer 

A device that converts coded characters to human-readable hard copy. 

Program 

The complete sequence of instructions, data, and routines necessary for the solu¬ 
tion of a problem. 


Program line 

A numbered group of data and instructions that, when combined with other lines, 
compose a program. A program line can contain one or more statements and can 
consist of one or more terminal or text lines. 
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Programming 

The process of planning, writing, testing, and correcting the steps required for a 
computer to solve a problem. 


Prompt 

A feature of time-sharing systems that requests user input. 


Punctuation 

Special language characters such as commas and separators. 

Quotation mark 

A character {” or ’) used in BASIC—PLUS to designate or delimit a string quantity. 

Radian 

A unit of plane angular measurement that is equal to the angle at the center of a 
circle subtended by an arc equal in length to the radius. 


Random number 

A number that is derived entirely by chance and is free from any bias toward 
predictable order. 

Record 

A group of data items treated as a unit. For example, a formatted ASCII record is a 
series of characters up to a line terminator (usually a carriage return/line feed), 
which ends the record. 

Recursive 

The repetitive process where the result of a cycle depends on the result of a previ¬ 
ous cycle. 

Reference 

Data that indicates the location of information. For example, a variable name in a 
program is a reference to a memory location that stores a value. 


Relationai operator 

A symbol or code that indicates the quantitative or qualitative relationship 
between two items of data. 


Remark 

See Comment. 
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RETURN key 

A terminal key that causes t 5 ^ed data to be input to the computer; see also 
Carriage return. 

Routine 

A set of instructions and data that performs one or more specific operations; a 
subdivision of a computer program. 


RUBOUT key 

See DELETE key. 


Run 

An instruction that transfers a program from a file to memory and initiates execu¬ 
tion; a single, continuous execution of a computer program or routine. 

Run time 

The time in which a program is executed; the actual amount of time required for a 
program to complete execution. 

Run>time system 

System software that manages part of the RSTS/E system. For example, 
the BASIC-PLUS nin-time system manages the BASIC-PLUS programming 
environment. 

Scientific notation 

Multiplication of a number by a power of 10. For example, "7000” can be 
"70 X 10^ ” or "7 X 10® ” in scientific notation. See also E format. 

Sequential file 

A storage unit in which data is available only in a consecutive sequence. 


Sign 


The symbol preceding a number that defines it as positive (+) or negative (-). 


Software 

All of the programs, procedures, rules, and peripheral information associated with 
the operation of a computer system. 


Sort 

The process of arranging items of information according to some portion of each 
item’s content. 
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Source language 

A language used by humans to write a computer program; the original form of a 
computer program before translation. 


Square root 

A factor of a number that, when squared, yields the number. 


Statement 

An expression or instruction written in a source language; an instruction to the 
computer to perform some operation. 

Statement separator 

A character or symbol that differentiates statements when two or more statements 
appear on the same program line. 


Step 

A single operation in a series of computer operations; to cause the execution of a 
single or specified number of operations. For example, the STEP value in a FOR 
loop increments or decrements the co\inter that determines how many times the 
loop will execute. 

Storage 

A general term for any device capable of retaining data; a device that receives, 
holds, and, at a later time, returns data; see also Memory. 


Storage location 

An identifiable area of memory that retains data. 


String 

A group of characters treated as a unit. 


String variable 

A variable that reserves a location in memory for character data. In 
BASIC—PLUS, you specify a string variable with a $ suffix, for example, A$. 


Subroutine 

A routine designed to be used by other routines to accomplish a specific task. 


Subscript 

A notation, written below and to the right of a set name, that represents a speci¬ 
fied item in that set; an integer that identifies a particular item in an array. For 
example, in A(0%), the subscript 0% identifies the first element in the array A. 
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Subscripted variable 

A variable name followed by one or more subscripts in parentheses; a notated 
variable that identifies the size of a storage location. For example, A(I%) is a 
subscripted variable. 

Substring 

One or more consecutive characters contained within a larger group of characters. 


Syntax 

The rules governing statement structure in a computer language; the structure of 
a language. 

System 

A combination of hardware and software that performs specific processing opera¬ 
tions; a collection of components that forms a functional unit. 

System commands 

Instructions that you give th| computer, such as RUN, which executes a program, 
and ASSIGN, which reserves’an I/O device. 

System manager 

The person in charge of a computer system. 


Table 

A collection of data stored for easy reference; data stored in an array of rows and 
columns; see also two-dimensional array. 

Terminal 

A device, consisting of a keyboard and display mechanism, used to enter and 
receive data to and from a computer; any device that can send and receive infor¬ 
mation over a communication channel. 

Terminal line 

A horizontal line on the terminal screen. On video terminals, you can usually 
enter 80 or 132 characters on one terminal line. 

Timesharing 

A method of computer operation in which the system is shared by more than one 
user in a timeframe that appears to be simultaneous. 
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Translate 


To convert source code into executable code. In BASIC-PLUS, translation occurs 
when you enter new statements, when you retrieve an existing source program 
with the OLD command, and when you run or chain to a source program. 


Truncate 

To reduce the size of a number by deleting one or more of the least significant 
digits; to drop digits from the end of a number, thus reducing precision. 


Two-dimensional array 

An array composed of columns and rows; a table. 


Unconditional branch 

An instruction that transfers program control to a specified location; an instruc¬ 
tion that interrupts an operation and shifts control to another operation. 


Underflow 

A condition that occurs because the result of a mathematical operation is smaller 
than the program can handle; a situation in which a computed nonzero quantity is 
less than the smallest nonzero quantity that the computer can store. 


Value 


A quantity; the information represented by a data item. 


Variable 

An entity that can assume any of a given set of values; the symbolic representa¬ 
tion of a storage location; a s 5 Tnbol whose value can change during a program. 


Warning 



error 

mistake in a program that is not severe enough to halt program execution. 


Warning message 

A notice from the computer that a warning error is present in the program. 


€ 
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examples of, 17-18 
moving data into I/O buffer, 17-14 
opening file, 17—3 
printing line on terminal, 17-18 
processing numeric data, 17-16 
reading a block, 17-5 
reading and writing data, 17-5 
reading magnetic tape file, 17-19 to 
17-20 

reading non-block I/O data, F-7 
reading virtual array data, F-9 
record blocking and deblocking, 17-20 
specifying number of characters to read, 
17-8 

specifying number of characters to write, 
17-7 

specifying offset into I/O buffer, 17-8 
storing numeric data in compact form, 
17-19 to 17-20 
writing a block, 17-5 
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Block I/O file 
access to, 14-5 
closing, 14-15 

printing on line printer, 17-19 
record format, 14-5 

BLOCK option, in GET and PUT statements, 
17-6 

Blocking record, definition, 17-20 
BPCREF listing 
cross-reference table, 6-17 
example of, 6-17f 
globed variable references, 6-19 to 
6-20 

header line, 6-17 

local variable references, 6-19 to 6-20 
printing on line printer, 6-15 
statistical data, 6-18 
suspect line numbers and veiriables, 

6-18 

variable reference codes, 6-18 

BPCREF program, 6-14 to 6-22 
command format, 6-15 
command switches, 6-16t 
error messages, 6-2 It 
output listing contents, 6-16 to 6-20 
running, 6-14 

sample cross-reference listing, 6-17f 
Branch 

conditional, 9-13,13-4, 13-5 
unconditional, 9-13 

Buffer 

allowed sizes for each device, 14-1 It 

default sizes for each device, 14—lit 

definition, 14-2 

determining size of, 17-3 

format of data in, 14-3 

setting size less than default, 14-12 

setting size of, 14-10 

Buffer, I/O, 14-2. See also Buffer 
BUFSIZ function, 17-3 
BYE command, ^1 

C 

Card reader, record characteristics, 17-6 
CATALOG command, 4-9 to 4—10 
CCL, 2-2 
command, 2-2 
command, entering, 2-3 
CCONT command, 6-9 
CCPOS function, 15-10 
with cursor control, 15-11 
use in program, 15-11 


CHAIN statement, 13—22 
and CTRL/C, 13-23 
effect on I/O channels, 13-23, 14—15 
file operations, 13-23 
with privileged programs, 13-23 
with source and translated progreuns, 
13-23 

CHANGE statement, 10-3 
Channel, I/O, 14—2. See also 110 
channel 

Channel 0, 14-3, 14-6 
Channel number, 14-2, 14-6 
Character data. See String data 
Character set, BASIC—PLUS, 8-1, D-1 
Characters, ASCII codes for, I>-3t 
Checksum, C-15 

CHR$ function, lO-lOt, 15-3 
CLOSE statement, 14—3,14-15 
for block I/O file, 14-15 
for formatted ASCII file, 14-15 
with negative channel number, 14-15 
for virtual array, 14-15, 16-5 
Cluster, disk, 14-12 

Cluster size 
negative, 14-13 
optimal size for file, 14-12 
pack, 14-12 
UFD, 14-13 

CLUSTERSIZE option, in OPEN statement, 
14-12 

Code 

ASCII character, D-3t 
source, 3-1 
translated, 3-2 
Command 
APPEND, 5-8 
ASSIGN, B-1 
BYE, B-1 

CATALOG, 4-9 to 4-10 
CCL, 2—2, 2—3 
CCONT, 6-8, 6-9 
COMPILE, 4-8, C-15 
CONT, 6-8, 6-9 
DCL, 2-2, 2-3 
DEASSIGN, B-2 
DELETE, 5-2 to 5-3 
EXTEND, 4-12, 7-9 
HELLO, B-2 
KEY, B-2 

keyboard monitor, 2-2 
LENGTH, 4-10 
list, 1^, 4-S 
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Command (Cont.) 

LISTNH, 4-5 
NEW, 1-3, 4-1 to 4-3 
NOEXTEND, 4-12 
OLD, 1-5, 4-4, C-15 
REASSIGN, B-3 
RENAME, 5-3 
REPLACE, 1-6, 5S 
RUN, 1-4, 4-6 
RUNNH,4-6 
SAVE, 1-5, 4-7 
SCALE, 4-11, 11-17 
summary, 3-2t 
TAPE, B-4 
UNSAVE, 5-6 to 5-7 
Commands, siunmary of, B-1 
Comments, 7-7 

continuing with ampersand/RETURN, 7-8 
continuing with LINE FEED key, 7-8 
optimizing use of, F-2 
Common memory, 13-23 
COMP% string arithmetic function, 10-21t 
Compatibility with BASIC-PLUS-2, hints for, 
E-1 

COMPILE command, 4-8, C-15 
Compiled program. See Translated 
program 

Concatenation, string, 8-10, 10-10 
Concise Command Language, 2-2. See 
also CCL 
Conditional 

branch, 9-13, 13-^, 13-5 
termination of FOR loop, 13-7 
transfer to subroutine, 13—4 
Constants, 8-3 
ambiguous, 11-14, F-3 
BASIC—PLUS optimization of, F-3 to F-4 
bytes nf translated code for, F-3 to F-4 
integer, 8—4, 11-4 
optimizing use of, F-3 
real (floating-point), 8-3 
string, 8—4, 10-1 
CONT command, 6-8, 6-9 
Control keys 
CTRL/C, 6-12 
CTRL/L, 10-8 
CTRL/0, 6-13 
CTRL/Q, 6-13 
CTRL/R, 4-2 
CTRL/S, 6-13 
CTRL/U, 4-2, 5-2 
CTRL/Z, 14-4 
summary of, B-6t 
Control variable, in loop, 9-17 


Conversion 
ASCII to string, 10-5 
integer array to string, 10-5 
string to ASCII, 10—4 
string to integer eirray, 10—4 
Core common, 13-23 
COS function, 9-28t 
COUNT option 

for disk, magnetic tape, and DECtape, 

17-8 

in GET statement, 17-8 
in PUT statement, 17-7 
for terminal, paper tape, and card reader, 
17-8 

CTRL/C, 6-5, 6-12 
. effect on I/O channels, 6-6, 6-8 
effect on program variables, 6-6, 6-8 
CTRL/C state. See Ready state 
CTRL/L, 10-8 
CTRL/0, 6-13 
CTRL/Q, 6-13 
CTRL/R, 4-2 
CTRL/S, 6-13 
CTRL/U, 4-2, 5-2 
CTRL/Z 

in formatted ASCU file, 14-4, 15-14 
with INPUT LINE statement, 15-16 
Current program, 3-2 
CVT functions, 17-16 
conversion of integer data, F-7f 
examples of, 17-17,17-19 to 17-20 
in LSET, RSET, and LET statements, 17—17 
with SWAP%, F-7 
CVT$$ function, 10-12 to 10-16 
bit mask in, 11-13 
with INPUT LINE statement, 15-16 
CVT$% function, 17-16t 
with file name string scan, 11-12 
CVT$F function, 17-16t 
CVT%$ function, 17-16t 
CVTF$ function, 17-16t 


D 

Data 

block I/O, 14-5 
constant, 8-3 
file, 14-1, 14-2 
floating-point, 8-2, 11-13. See 
also Floating-point data 
floating-point, conversion with CVT 
functions, F-8f 

floating-point (in virtual array), 16-6 
formatted (stream) ASCII, 14—4 
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Data (Cont.) 

integer, 8-2, 11-1. See also 
Integer 

integer, conversion with CVT functions, 
F-7f 

integer (in virtual array), 16-6 
printing on line printer, 17-19 
printing on terminal, 9-3, 15-2, 17-18 
printing to file or device, 15-3 
reading from formatted ASCII file, 

15-13 

reading from terminal, 15-11 
real, 8-2 
string, 8-2, 10-1 

string (in virtual array), 16-2, 16-6 
supplying to running program, 9-7, 15-11 
tailoring output format of, 15—4 
variable, 8-5, A-1 
virtual array, 14—4 
Data file, 14-1, 14-2 
DATA statement, 9-9 to 9-11, 10-6 
Data types, 8-3t 

DATE$ string function, 10-llt, 13-18t 
DCL 

keyboard monitor, 2-2 
run-time system, 2-2 

DCL commands, 2-2 
APPEND, compared to BASIOPLUS 
APPEND command, 5-9, B-1 
ASSIGN, compared to BASIC—PLUS 
ASSIGN command, B-1 
BASIC/BPLUS, 2-4 
DEASSIGN, compared to BASIC-PLUS 
DEASSIGN command, B-2 
DELETE, compared to BASIC-PLUS 
DELETE command, 5-3, B-2 
entering, 2—3 

RENAME, compared to BASIC—PLUS 
RENAME command, 5—4, B—3 
DEASSIGN command, B-2 
compared to DCL DEASSIGN command, 
B-2 

Deblocking record, definition, 17-20 
Debugging a program, 6-8 to 6-13 
example of, 6-10 
DECtape 

as file-structured device, 14-10 
buffer size, 14-11 
OPEN statement for, 14-8 
record characteristics, 17-6 
DEF* statement, 9-31 
arguments, 9-31, 9-33 
multi-variable, 9-34 


DEF* statement (Cont.) 
multiple-line, 13-1 
for string functions, 10-18 
Default keyboeird monitor, 2-2 

DELETE command, 5-2 to 5-3 
compared to DCL DELETE command, 5-3, 
B-2 

DELETE key, 1^, 4-2, 5-2 
Delimiters 

carriage return/line feed, 10—8, 14—4 
ESCAPE, 10-8, 14-4 
form feed, 10-8, 14—4 
in formatted (stream) ASCII file, 14—4 
for INPUT LINE statement, 10-8 
line feed, 10-8, 14—4 
vertical tab, 14-4 
DET matrix fimction, 12-8 
Devices 

file-structured, 14-2,14-10 
non-file-structured, 14-2, 14-10 
record characteristics, 17-6t 
DIF$ string arithmetic function, 10-20t 

Difference, logical, 11-10 
DIGITAL Command Language, 2-2. See 
also DCL 

DIM statement, 9-26, 12-1 
virtual array, 16-2 

Directory listing, displaying, 4-9 to 4-10 
Disk 

6is file-structured device, 14-10 
buffer size, 14-11 

default RECORDSIZE in block I/O, 17-6 
opening for non-file-structured processing, 
14-10 

record chjiracteristics, 17-6 
Disk access time, decreasing, F-5 
Disk file 
extending, 17-9 

locking and unlocking blocks in, 17-21 
multi-user access to, 17-21 
preextending to more than 65535 blocks, 
14-14 

preextending with FILESIZE option, 

14-14 

Diskette, buffer size, 14-11 
Division with integers, 11-4 
DMCll/DMRll, buffer size, 14-11 
Dummy variables, 9-12 

E 

E format, 8-3 

END statement, 6-6, 6-8, 9-37 
effect on I/O channels, 6-6, 6-8 
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END statement (Cont.) 
effect on program variables, 6-6, 6-8 
explicit, 6-6 
implicit, 6-6 

EQV logical operator, 8-15 
ERL variable, 6-6, 6-8, 13-17 
ERR variable, 6-6, 6-8, 13-15, C-2 
Error, untrapped 
definition, 6-5 

effect on I/O channels, 6-6, 6-8 
effect on program variables, 6-6, 6-8 
Error handling subroutine, 13-14 to 13-18 
disabling, 13-16 

transfer of control to multi-statement line, 
13-16 
Errors 

abbreviations in descriptions, C-2t 
BASIC-PLUS, C-1 
checksum, C-15 
disk, C-15 
fatal, C-2 
information, C-2 
multiple meanings for, C-3 
nonrecoverable, C-lOt to C-14t 
nontrappable, C-3t 
?Program lost-sorry message, C—14 
RSTS/E, C-1 
severity, C-2t 
trapping, C-1, C-2 
user-recoverable, C-4t to C-lOt 
warning, C-2 
ESCAPE key, 10-8 
Exclusive OR logical operator, 8-15 
Exclusive OR operation, diagram, 11-10 
Executable program 
file size, 4-9 
protection code, 4—9 
Execution 

halting with CTRL/C, 6-5, 6-12 
halting with STOP statement, 6-5, 6-8, 
9-38 

suspending with SLEEP statement, 13-20 
EXP function, 9-28t 
Exponential format, 8-3 
Expressions, 7-3, 8-7 to 8-17 
arithmetic, 8-8 
logical, 8-14,11-6 
logical, evaluation of, 11-7 
numeric relational, 8-11 
relational, 8-10 
relational, evaluation of, 11-6 
string, 8-10 
string relational, 8-12 
use of parentheses in, 8-16 


EXTEND command, 4-12, 7-9 
EXTEND mode, 4-12, 7-9 
EXTEND program format, 7-lOf 
comments, 7-12 
line continuation, 7-12 
spaces and tabs, 7-11 
variable and function names, 7-11 
EXTEND statement, 7-9 


F 

FIELD statement, 17-12 
multiple definitions for same buffer, 

17-14, 17-18 

processing string with, 17-21 
use in record blocking and deblocking, 
17-20 

use of subscripted string variables in, 
17-13 

virtual array strings in, 17-14 
File 

•BAC, 3-2, C-15 
.BAC, size of, C-16 
•BAS, 3-1 
block I/O, 14—5 

changing name, type, or protection code, 
5-4,14-16 
closing, 14-3, 14-15 
data, 14-1,14-2 

deleting from directory, 5-6, 14-17 
extending a (disk), 17-9 
formatted (stream) ASCII, 14—4, 15-3, 
15-13 

opening, 14-2,14-6 

preextending to more than 65535 blocks, 
14-14 

preextending with FILESIZE option, 

14-14 

read and write access to, 14-8 
reading and writing, 14-3 
sharing, 17-21 

virtual array, 14—4, 16-1. See also 
Virtual arrays 

File name string scan, 11-12 

File specification, RSTS/E, 4-4, 4-6, 4-8, 

5-6 

switches, 14-7 

File-structured devices, 14-2,14-10 
FILESIZE option, in OPEN statement, 14—14 
/FILESIZE switch, 14-14 
FIX function, 9-28t 
Floating-point 
arithmetic, 11-13 

arithmetic, accumulated error, 11-13 


o 


Index—5 




Floating-point (Cont.) 
constants, 8-3 
variables, 8-6 
Floating-point data, 8-2 
assigned to integer, 11-4 

conversion with CVT functions, F-8f 
precision, 11-13 
range of values, 11-13 
in virtual array, 16-6 
FOR loops 

conditional termination of, 13-7 
implied, 13-11, F-4 

FOR statement, 9-17 
FOR statement modifier, 13-11 
Foreign buffers, 17-10. See also 
Alternate buffer 110 
Format 

of data in buffer, 14-3 
exponential, &-3 
program, 7-10 

of statements, optimizing, F—1 
Format field, 15—4. See also 
PRINT-USING format field 
Formatted ASCII file, 15-3 
access to, 14-4,15-1 
closing, 14-15 

reading data from, 15-13, 15-14 
record delimiters, 14-4,15-14 
record format, 14—4, 15-14 
record length, 15-4,15-14 
writing data to read with INPUT statement, 
15-3 

writing nonprinting ASCII values, 15-3 

Formatted ASCII I/O, 14-5, 15-1 
examples, 15—17 to 15-19 
Formatting characters, 15-2 
in formatted ASCII file, 15-3 
Functions 
ABS, 9-28t 
ASCn, lO-lOt 
ATN, 9-28t 
BUFSIZ, 17-3 
CCPOS, 15-10 
CHR$, lO-lOt, 15-3 
COMP%, 10-21t 
COS, 9-28t 
CVT, 17-16 
CVT$$, 10-12, 10-12t 
CVT$%, 17-16t 
CVT$F, 17-16t 
CVT%$, 17-16t 
CVTF$, 17-16t 


Fimctions (Cont.) 

DATE$, 10-llt, 13-18t 

DET, 12-8 

DIF$, 10-20t 

EXP, 9-28t 

FIX, 9-28t 

INSTR, lO-lOt 

INT, 9-28t, 9-28 

integer, user-defined, 11-5 

INV, 12-8 

LEFT, 10-9t 

LEN, lO-lOt 

LOG, 9—28t 

LOGIO, 9-28t 

MAGTAPE, 13-20 

matrix, 12-8 

MID,lO-lOt 

NUM$, 10-llt 

NUM1$, 10-llt 

PI, 9-28t 

PLACE$, 10-21t 

POS, 15-10 

PRINT, 15-10 

PROD$, 10-20t 

QUO$, 10-20t 

RAD$, lO-lOt 

recursive, 13-2 

RIGHT, lO-lOt 

RND, 9-28t, 9-29 

SGN, 9-27, 9-28t 

SIN,9-28t 

SPACE$, lO-lOt 

SPEC%, 13-20, 17-21 

SQR, 0-28t 

string, 10-9 

string, user-defined, 10-18 

string arithmetic, 10-20t 

string arithmetic, nesting, 10-24 

STRING$, 10-12t, 15-3 

SUM$, 10-20t 

summary of, A-2 

SWAP%, 17-11, 17-17 

SYS, 11-11, 13-20 

TAB, 15-10 

TAN, 9-28t 

TIME, 13-19t 

TIME$, 10-llt, 13-19t 

TIME$, format examples, 13—20t 

TRN, 12-8 

user-defined, 9-31 

user-defined, multiple-line, 13-1 

VAL, 10-llt 

XLATE, 10-12t, 10-17 
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G 

GET statement, 17-5 
GOSUB statement, 9-36 
GOTO statement, 6-8, 9-13 
in debugging, 6-9 

H 

Header 

program, 4-5, 4-6 
statement, F— 1 . See also Statement 
header 

HELLO command, B-2 
Hints 

for BASIC-PLUS-2 compatibility, El-1 
programming, F—1 

I 

I/O 

alternate buffer, 14-12,17-10 
block, 17-1. See also Block HO 
formatted ASCII, 14r-5, 15-1 
formatted ASCII (examples), 15—17 to 
15-19 

terminating, 14-15 
virtual array, 16-1. See also 
Virtual arrays 

I/O buffer, 14-2. See also Buffer 
I/O channel, 6-6, 14-6 
closing, 13-23, 14-15 
definition, 14-2 

determining buffer size of, 17-3 
effect of CHAIN on, 13-23 
opening terminal as, 15-15 
I/O methods, 14-4 to 14-6 
IF-GOTO statement, 6-13 to 9-15 
IF statement, 9-13 to 9-15 
IF statement modifier, 13-10 
IF—THEN—ELSE statement, 13—5 
IF-THEN statement, 9-13 to 9-15 
Inomediate mode 
debugging in, 6-8 
description, 1-2, 6-2 to 6-4 
examples, 6-2 
limitations, 6-3 
variable assignments, 6-3 
IMP logical operator, 8-15 
Infinite loop, 6-5 

INPUT LINE statement, 10-7, 15-15 
delimiters for, 10-8 
handling of carriage return character, 
15-16 

record length for, 15-16 


INPUT statement, 9-7,10-7,15-11 to 
15-15 

errors, 15-12 

reading data from file, 15-13 
reading data from terminal, 15-11 
record length for, 15-14 
use of prompting message in, 9-8, 15-11 
INSTR string function, lO-lOt 
INT function, 9-28t, 9^28 
Integer, 8-2 
arithmetic, 11-4 
as bit pattern, 11-2 
as logical value, 11-8 
as number, 11-1 
constants, 8-4, 11—4 
conversion with CVT functions, F-7f 
division, 11-4 

finding value from bit pattern, 11-3 
functions, user-defined, 11-5 
I/O, 11-5 

internal format, ll-2f 
in logical operations, 11—2, 

11-6 to 11-13 
storage, 11-1 
value range, 11-1 
variables, 8^, 11-4 
in virtual array, 16-6 
Integer function, INT, 9-28 
Integers, optimizing use of, F-3 
INV matrix fimction, 12-8 


J 

Job 

calling from SLEEP state, 13-21 
definition, 2-1 
Job keyboard monitor, 2-2 


K 

KEY command, B—2 
Keyboard 
buffer size, 14-11 
record characteristics, 17-6 
Keyboard monitor, 2-1 
command, 2-2 
default, 2-2 
job, 2—2 

wait state. See Ready state 
Keywords, 7-3, 8-1 
list of reserved, A-20t 
KILL statement, 5-7, 14-17 
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LEFT string function, 10-9t 
LEN string function, lO-lOt 
LENGTH command, 4-10 
LET statement, 9-2 
effect on string variables, 17-15 
Line 

continuation, 7-4 
multi-statement, 7-4 

multi-statement, as spacesaving technique, 
F-2 

multi-statement, in immediate mode, 0-4 
program, 7-4 
terminal, 7—4 
t»0xt) 7“"4 

UNE FEED key, 7-5, 7-8, 10-8,14-4 

Line numbers, 7-1 

Line printer, buffer size, 14-11 

LINE variable, 8-6, 6-8, 6-13, 13-17 

LIST command, 1—4, 4r-6 

LISTNH command, 4-5 

Literal, 15-9 

Lock 

explicit, 17-21 
implicit, 17—21 

releasing with UNLOCK statement, 17—21 
LOG function, 9-28t 
LOGIO function, 9-28t 
Logical 

difference, 11-10 
expressions, 8-14,11-6 
expressions, evaluation of, 11-7 
operators, 8-15,11-6 
product, 11—9 
sum, 11—10 

values. See Logical values 
Logical operations 
how BASIC-PLUS performs, 11-8 
programming applications, 11-11 
truth values for, 8-15t, 11—9t 
Logical operators 
AND, 8-15t 
EQV, 8-15t 
IMP, 8-15t 
NOT, 8-15t 
OR, 8-15t 
XOR, 8-15t 
Logical values, 8-10 
-1% and 0% as, 11-6 to 11—7 
integers as, 11-8 
in relational expressions, 11-6 
storing, 11-7 
testing, 11-7 
Loop index, 9-17 


Loops, 9-15 to 9-24 
FOR, conditional termination of, 13-7 
FOR, implied, 13-11, F-^ 

FOR-NEXT, 9-17 
nested, 9-20 
parts of, 9-17 

transferring control in and out of, 9-21 
types of, 9-17 
UNTIL-NEXT, 9-23 
WHILE-NEXT, 9-22 
LSET statement, 17-14 
effect on string length, 17-14 
effect on string variables, 17-15 


M 

Magnetic tape 

as file-structured device, 14-10 
buffer size, 14—11 
OPEN statement for, 14-8 
record characteristics, 17-6 
MAGTAPE function, 13-20 
Mask, bit, 11-12. See also Bit mask 
MAT initialization statement, 12-6 
MAT INPUT statement, 12-4, 15-16 
MAT PRINT statement, 12-2, 15-9 
MAT READ statement, 12-2 
MAT statements, 12-1 
Mathematical functions, 9-27 
Matrices, conforming, 12-8 
Matrix 

calculations, 12-7 
determinant, 12-8 
functions, 12-8 
initializing, 12-6 

input from file with MAT INPUT, 15-16 
input from terminal with MAT INPUT, 
12-4, 15-16 
inversion, 12-8 
manipulation, 12-1 

printing to file with MAT PRINT, 15-9 
printing to terminal with MAT PRINT, 
12-2,15-9 

reading with MAT READ, 12-2 
transposition, 12-8 
MID string function, lO-lOt 
Mixed-mode arithmetic, 11-14 to 11-15 
Mode 

read only, 14-8 
update, 14—8 
MODE 1%, 17-21 
MODE option, 14—8, 17-21 
MODE option, in OPEN statement, 14-14 
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Modifiers 

FOR statement, 13-11 
IF statement, 13-10 
multiple statement, 13-14 
nested, 13-11 

summary of statement, A-18 
UNLESS statement, 13-11 
UNTIL statement, 13-13 
WHILE statement, 13-12 
Multi-line statement, 7-5 
Multi-statement line, 7-4 
as spacesaving technique, F-2 
and error-handling subroutine, 13-16 
in immediate mode, 6-4 

N 

NAME-AS statement, 5-4, 14-16 
for nonprivileged users, 5-5 
for privileged users, 5-5 

Nesting 

FOR-NEXT loops, 9—20 
IF statements, 13^ 
multiple-line DEF* functions, 13-3 
string arithmetic functions, 10-24 
subroutines, 9-36 
techniques, 9-20f 

NEW command, 1-3, 4-1 to 4-3 
NEXT statement, 9-18 
NO SCROLL key, 6-14 
NOEXTEND command, 4—12 
NOEXTEND mode, 4-12, 7-9 
NOEXTEND program format, 7—lOf 
comments, 7-12 
line continuation, 7-12 
spaces and tabs, 7-11 
variable and function names, 7-11 

Non-file-structured devices, 14—2, 14-10 
NOT logical operator, 8-15 
Null device 

in alternate buffer I/O, 17-11 
buffer size, 14—11 
use with FIELD statement, 17-21 
Null string, 10-2 
in INSTR function, 10-10 
in relational expressions, 8-14 
symbol for, 8-14 

NUM variable, 12-5 
NUM$ string function, 10-1 It 
NUM1$ string function, 10-1 It 
NUM2 variable, 12-5 
Numbers, floating-point, 11-13. See 
also Floating-point data 


O 

OLD command, 1-5, 4—4, C-15 

ON ERROR GOTO statement, 6-5, 13-15, 
15-12, C-1, C-2 

ON-GOSUB statement, 13—4 

ON-GOTO statement, 13—4 

OPEN FOR INPUT, 14-7 

OPEN FOR OUTPUT, 14-8 

OPEN statement, 14-2,14-3, 14-6 to 
14-14 

creating file, 14-8 
defaults in, 14-6 
errors, 14-9t 

for file-structured and non-file-structured 
devices, 14-6 
forms of, 14-7 
opening existing file, 14-7 
options, 14—7, 14-10 
options, order of, 14-7 
read/write access with, 14-8 
for virtual array, 16-3 

Operand, 7-3 

Operators, 7—3 
arithmetic, 8-9t 
logical, 8-15,11-6 
numeric relational, 8-1 It 
precedence rules for, 8-16t 
relational, 11-6 
string relational, 8-12t, 10^ 
smnmary of, A-2 

Optimizing 
constants, F-3 
files, F-5 to F-6 
integers, F—3 
statement formats, F-1 
statement structure, F—4 to F-5 
strings, F—6 
variables, F-2 

Optional features of BASIC-PLUS, 1-1 

Options 

BLOCK, 17-6 
CLUSTERSIZE, 14-12 
COUNT, 17-7 
FILESIZE, 14-14 
MODE, 14-8, 14-14, 17-21 
RECORD, 17-7 
RECORDSIZE, 14-10 
USING, 17-8 

OR logical operator, 8-15 

OR operation, diagram, 11-10 
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p 

Pack cluster size, 14-12 

Paper tape, record characteristics, 17-6 

Paper-tape punch, buffer size for, 14—11 

Paper-tape reader, buffer size for, 14-11 

Parentheses, use in expressions, 8—16 

Parity bit, 10-13 

PI function, 9-28t 

PLACE$ string arithmetic function, 10-21t 
POS function, 15-10 
Precision, string arithmetic, 10—21 
values in PROD$, QUO$, and PLACE$ 
functions, 10-24t 
PREFIX key, 10-8 
PRINT statement, 9-3, 10-9, 15-1 to 
15-4 

formatting characters in, 9-5, 9-6 
functions, 15-10 
output rules, 15-2 
printing numbers, 9-4, 15-2 
printing strings, 9-5,15-2 
in scaled arithmetic, 11-17 
specifying output format, 9-5, 9-6, 

15-2 

suppressing carriage return/line feed, 
9-7,15-2 

PRINT-USING format field 
asterisk fill, 15-6 
comma and semicolon in, 15-8 
commas in numeric field, 15-7 
dollar sign, 15-7 
exclamation point, 15-4 
exponential format, 15-6 
insufficient numeric format, 15-7 
literal cheuracters in, 15-8 
numeric field, 15-5 
numeric format too large, 15-8 
string field, 15-4, 15-5 
trailing minus sign, 15-6 

PRINT-USING statement, 15-4 to 15-9 
printing numbers with, 15-5 
printing strings with, 15—4 
in scaled arithmetic, 11-17 
Print zones 

in formatted ASCII file, 15-3 
printing data in, 9-5, 9-6, 15-2 
size of, 9-5,15-2 

Problems, software, reporting, C-16 
PROD$ string arithmetic function, 10-20t 

Product, logical, 11-9 
Program 
.BAG, 3-2, C-15 
.BAS, 3-1 


Program (Cont.) 
chaining to, 13-22 
changing file name, 5—4 
changing file type, 5-4 
changing name, 5-3 
changing protection code, 5-4 
changing scale factor, 11-18 
character set for, 8-1, D-1 
compiled. See Program, translated 
context, definition, 6-5 
continuing execution and detaching job with 
CCONT, 6-9 

continuing execution with CONT, 6—9 
continuing execution with GOTO, 6—9 
correcting syntax errors, 4-3 
correcting typing errors, 1-4, 4-2 
creating new, 1-3, 4-1 
creating with text editor, 4-3 
current, 3-2 
debugging, 6-8 to 6-13 
debugging, example of, 6-10 
deleting from disk storage, 5-6 
displaying length in memory, 4-10 
displaying on terminal, 1-4, 4-5 
documenting, 7-6 
editing, 5-1 

entering statements, 4—2 
erasing lines, 5-2 to 5-3 
formatting, 7-4 

halting and checking execution, CTRL/C 
and PRINT LINE, 6-12 
halting execution with STOP, 6-8, 9-38 
header, 4-5, 4-6 
line, 7-4 

listing on terminal, 1—4, 4-5 
in memory, 3-2 
modifying, 5-1 
optimizing, F-1. See also 
Optimizing 
parts of a, 7-1, 7-3 
printing on line printer, 4-8 
recompiling, C-15 
replacing saved, 1-6 
replacing saved source, 5-6 
retrieving source from disk, 1—5, 4—4 
running, 1-4, 4-6 
nmning current, 4-6 
running saved, 4-6 
sample of, 7-2 

saving source on disk, 1—5, 4—7 
saving translated (executable) on disk, 

4-8 

source, 3-1 

suspending execution, 13-20 
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Program (Cont.) 
symbols in, D-lt 
transferring control to, 13-22 
translated, 3—2 

translation of source code into executable 
code, 4-3 

use of spaces and tabs in, 7-6 
?Program lost-sorry error 
causes, C—15 
description, C-14 
Programming hints, F-1 
Programs, combining in memory, 5-8 
/PROTECT switch, 4-9, 5-4, 14r-7, 14-17 
Protection code, 14-7,14-8 
chemging, 5-4, 14-16 
PUT statement, 17-5 


Q 

QUO$ string arithmetic function, 10-20t 


R 

RAD$ function, lO-lOt 
Random access, 17-6 
Random number fiinction, RND, 9-29 
RANDOMIZE statement, 9-30 
READ statement, 9-9 to 9-11, 10-6 
Ready state 
definition, 6-4 

effect on privileged program, 6-6, 6-8 
entering, 6-4, 6-5 
possible actions in, 6-7 
program status in, 6-6, 6-8t 
Real data, 8—2. See also 
Floating-point data 
REASSIGN command, B-3 
Record blocking and deblocking 
definition, 17-20 
example, 17-20 

use of FIELD statement in, 17-20 
Record characteristics 
for card reader, 17-6 
for DECtape, 17-6 
for disk, 17-6 
for magnetic tape, 17-6 
for paper tape, 17-6 
for terminal, 17-6 

RECORD option, in GET and PUT statements, 
17-7 

RECORDSIZE option, in OPEN statement, 
14-10 

RECOUNT variable, 17-8, 17-8 
Recursive function, 13-2 


Relational 
expressions, 8-10 
expressions, evaluation of, 11-6 
operators, 8-11, 8-12, 11-^ 

REM statement, 7-7 
Remarks, 7-7 
RENAME command, 5-3 
compared to DCL RENAME command, 5—4, 
B-3 

REPLACE command, 1-6, 6-6 
Reporting software problems, C-16 
RESTORE statement, 9-12 
RESUME statement, 13-15 
transfer of control to multi-statement line, 
13-16 

RETURN key, 1-3,10-8, 14-4 
RETURN statement, 9-36 
RIGHT string function, lO-lOt 
RND function, 9-28t, 9-29 
/RONLY switch, 14-8 
RSET statement, 17-14 
effect on string length, 17-14 
effect on string variables, 17-15 
RSTS/E file specification, 4-4, 4-6, 4-8, 

5-6 

switches, 14-7 
RUBOUT key, 4-2, 5-2 
RUN command, 1-4,4-6 
Rim-time system 
BASIC-PLUS, 2-2, C-16 
definition, 2-1 
RUNNH command, 4-6 

S 

SAVE command, 1-5, 4-7 
SCALE command, 4-11,11-17 
Scale factor, 11-15 
with .BAG files, 11-19 
changing, 11-18 
current, 4-11,11-17 
default value, 4-11,11-15 
displaying, 4-11, 11-18 
effect on floating-point calculations, 

11-16 

with immediate mode statements, 11-19 
pending, 4-11, 11-17 
resetting to default value, 11-19 
values for, 11-15 
Scaled arithmetic, 11-15 to 11-19 
SGN function, 9-27, 9-28t 
Sign bit, 11-2 
Sign function, SGN, 9-27 
SIN function, 9-28t 
SLEEP statement, 13-20 
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Software Performance Report (SPR), C-2 
Software problems, reporting, C-16 
Source program, 3-1 
retrieving from disk, 4—4 
saving on disk, 4—7 

SPACE$ string function, lO-lOt 
SPEC% function, 13-20, 17-21 
SPR, C-2 

SQR function, 9-28t 
Statement, definition, 7-3 
Statement header 
definition, F-1 
saving space in, F-2 
Statement modifiers, 13-10 
efficient use of, 13—10, F—4 
summary of, A-18 

Statements 
CHAIN, 13-22 
CHANGE, 10-3 
CLOSE, 14-15 
DATA, 9-9,10-6 
DEF*, 9-31, 10-18 
DEF*, multiple-line, 13-1 
DIM, 9^26,12-1 
DIM, virtual array, 16-2 
END, 6-8, 9-37 
ending, 1-3 
EXTEND, 7-9 
FIELD, 17-12 
FOR, 9-17 
GET, 17-6 
GOSUB, 9-36 
GOTO, 6-8, 6-9, 9-13 
IF-GOTO, 9-13 
IF-THEN, 9-13 
IF-THEN-ELSE, 13-5 
INPUT, 9-7, 10-7, 15-11 to 15-15 
INPUT LINE, 10-7,15-15 
KILL, 5-7, 14^17 
LET, 9-2 
LSET, 17-14 
MAT initialization, 12-6 
MAT INPUT, 12-4, 15-16 
MAT PRINT, 12-2, 15-9 
MAT READ, 12-2 
multi-line, 7-5 
NAME-AS, 5-4, 14-16 
NEXT, 9-18 

ON ERROR GOTO, 13-15, C-1, C-2 
ON-GOSUB, 13-4 
ON-GOTO, 13-4 
OPEN, 14-6 

optimizing format of, F-1 


PRINT, 9-3, 10-9, 15-1 to 15-4 

PRINT-USING, 15-4 to 15-9 

PUT, 17-5 

RANDOMIZE, 9-30 

READ, 9-9, 10-6 

REM, 7-7 

RESTORE, 9-12 

RESUME, 13-15 

RETURN, 9-36 

RSET, 17-14 

SLEEP, 13-20 

STOP, 6-8, 9-38 

summary of, A-3 to A-18 

UNLOCK, 17-21 

UNTIL, 9-23 

WAIT, 13-21 

WHILE, 9-22 

STATUS variable, 11-11, 14-8, 17-3 
bit tests, 17-4t 
with virtual arrays, 16-12 
STEP expression, 9-18 
STOP statement, 6-5, 6-8, 9-38 
effect on error-handling routines, 9-38 
effect on I/O channels, 6-6, 6-8 
effect on program variables, 6-6, 6-8 
Stream ASCII file, 15-3 
access to, 14-4, 15—1 
closing, 14—15 

reading data from, 15-13, 15-14 
record delimiters, 14-4, 15-14 
record format, 14-4, 15-14 
record length, 15-4, 15-14 
writing data to read with INPUT statement, 
16-3 

writing nonprinting ASCII values, 15-3 
Stream ASCII I/O, examples, 15-17 to 
15-19 
String 

arithmetic, 10-19 

arithmetic, precision, 16-21 

ASCII conversions, 10-3 

concatenation, 8-10, 10-10 

constants, 8-4, 10-1 

conversion with CVT$$ function, 10-12 

data, 8-2, 10-1 

efficient use of, F-6 

expressions, 8-10, 8-12 

functions, 10-9 

functions, user-defined, 10-18 

input from file using INPUT LINE, 15-15 

input using INPUT, 10-7 

input using INPUT LINE, 10-7, 15-15 

input using READ and DATA, 10-6 

null, 10-2 
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String (Cont.) 
output, 10-9 

relational operators, 10-3 
size, 8-5,10-3 

subscripted variables, 10-2, 17-13 
translation with XLATE function, 10-17 
variables, 8-7,10-1 

variables, effect of FIELD statement on, 
17-12 

variables, effect of LET statement on, 
17-15 

variables, effect of LSET and RSET 
statements on, 17-15 
in virtual array, 16-2, 16-6 
STRING$ string function, 10-12t, 15—3 
Subroutines, 9-35 
calling, 9-^6 

conditional transfer to, 13—4 
exiting, 9-36 
nesting, 9-36 

saving program space with, F-5 
Subscripted variables, 9-24 to 9-27 
in FIELD statement, 17-13 
Sum, logical, 11-10 

SUM$ string arithmetic function, 10-20t 
Suspending program execution, 13-20 
SWAP% function, 17—17 
in alternate buffer I/O, 17-11 
with bit mask, 11-12 
with CVT functions, F—7 
effect on integer, 17-18 
examples of, 17-18 
uses of, 17-18 
Switch 

/FILESIZE, 14-14 
/PROTECT, 4-9, 5-4, 14-7, 14-17 
/RONLY, 14-8 

in RSTS/E file specification, 14-7 
SWITCH program, 2-4 
Symbols, in programs, D-lt 
S}mtax error, correcting, 4-3 
SYS function, 11-11, 13-20 


T 

TAB function, 15-10 
TAB key, B-5 
TAN function, 9-28t 
TAPE command, B—4 
TEMPnn.TMP file, 4-3 
Terminal 
buffer size, 14-11 
opening as I/O channel, 15-15 


Terminal (Cont.) 
opening in special mode, 15-15 
record characteristics, 17-6 
Terminal keys, summary of, B-5t 
Terminal line, 7-4 
Terminal output 
controlling, 6-13 to 6-14 
stopping with CTRL/0, 6-13 
suspending and resuming with CTRL/S and 
CTRL/Q, 6-13 

suspending and resuming with NO SCROLL 
key, 6-14 
Text line, 7-4 
TIME function, 13-19t 
TIME$ string function, 10-1 It, 13-19t 
format examples, 13-20t 
Translated program, 3-2 
file size, 4—9 
protection code, 4-9 
TRN matrix function, 12-8 
Two's complement arithmetic, 11-3 

U 

UFD, 14-13 

Unconditional branch, 9-13 
UNLESS statement modifier, 13-11 
UNLOCK statement, 17-21 
UNSAVE command, 5-6 to 5-7 
UNTIL statement, 9-23 
UNTIL statement modifier, 13-13 
Update mode, 14-8, 17-9, 17-21 
and virtual arrays, 16-12 
User-defined functions, 9-31 
integer, 11-6 
multiple-line, 13-1 
string, 10-18 

User File Directory, 14-13 
USING option, in GET and PUT statements, 
17-8 

V 

VAL string function, 10-1 It 
Values, logical. See Logical values 
Variables, 8-5 
assigning values to, 9-2 
ERL, 6-6, 6-8, 13-17 
ERR, 6-6, 6-8, 13-15, C-2 
initial values for, 8-6 
integer, 8-6, 11-4 
LINE, 6-6, 6-8, 6-13, 13-17 
naming, 8-6, A-1 
NUM, 12-5 
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Variables (Cont.) 

NUM2, 12-5 
optimizing use of, F-2 
real (floating-point), 8-6 
RECOUNT, 17-8, 17-9 
STATUS, 11-11, 14-8, 17-3 
string, 8-7, 10-1 

string, effect of FIELD statement on, 

17-12 

string, effect of LET statement on, 

17-15 

string, effect of LSET and RSET statements 
on, 17-15 

subscripted, 9-24 to 9-27, 17-13 
summary of, A-1, A-2 
temporary, F-2 
Virtual array file 
access to, 14-4 
record format, 14-4 
Virtual arrays, 14-5, 16-1, 16-14 
accessing algorithm, F-lOf 
buffer size, 16-4 

changing values of elements in, 16-13 
CLOSE with negative channel number, 
16-5 

closing file, 14-15, 16-5 

compared with memory arrays, 16—1, 16-2 

DIM statement, 16-2 

effect of CHAIN statement on, 13-23 

efficient referencing of, 16-7, 16-9, 

16-14 


Virtual arrays (Cont.) 

examples of referencing, 16-7, 16-9, 
16-14 

examples of using, 16-12 

file layout, 16-8f 

initializing, 16-4 

open on two I/O channels, 16-11 

opening file, 16-3 

preallocating size of, 16-11 

preextending, 16-4 

reading with block I/O, F-9 

RECORDSIZE values for, 16-4 

simultaneous access of, 16-12 

storage bn disk, 16-5 

string length, 16-2, 16-6 

string storage in, 16-2, 16-6 

trailing null characters in, 16-3, 16-6 

two-dimensional, 16-7 


W 

WAIT statement, 13-21 
WHILE statement, 9-22 
WHILE statement modifier, 13-12 


X 

XLATE string function, l()-12t, 10-17 
XOR logical operator, 8-15 
XOR operation, diagram, 11-10 
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